147 lines
6.1 KiB
Plaintext
147 lines
6.1 KiB
Plaintext
=head1 INTRODUCTION
|
|
|
|
The content of this distribution is a new, experimental web frontend for the
|
|
Netdisco network management tool. See L<http://netdisco.org/> for further
|
|
information on the project.
|
|
|
|
If you have any trouble getting the frontend running, or it blows up in your
|
|
face, please contact C<oliver> in the C<#netdisco> IRC channel (on freenode).
|
|
|
|
=head1 INSTALLATION
|
|
|
|
Download the tarball from GitHub and extract it on your system. Make sure the
|
|
system has access to your Netdisco database.
|
|
|
|
https://github.com/ollyg/netdisco-frontend-sandpit/tarball/master
|
|
|
|
Edit the C<Netdisco/environments/development.yml> file to have the correct
|
|
credentials and settings (host name) for your own Netdisco database.
|
|
|
|
In the same file, uncomment the C<no_auth> setting if you use Apache auth.
|
|
Currently the frontend only works with the built-in Netdisco authentication.
|
|
|
|
Optionally, in the same file uncomment and edit the C<domain_suffix> setting
|
|
to be appropriate for your local site (same as the C<domain> setting in
|
|
C<netdisco.conf>).
|
|
|
|
=head2 Dependencies
|
|
|
|
You will need to have Netdisco itself installed on the system as this module
|
|
will try to load the C<netdisco.pm> library.
|
|
|
|
To avoid muddying your system, use the following shell script to download and
|
|
install Perl dependencies into a custom library path:
|
|
|
|
curl -L http://cpanmin.us/ | perl - --notest --quiet --local-lib-contained "${HOME}/perl-profiles/netdisco-web" \
|
|
App::cpanminus \
|
|
App::local::lib::helper \
|
|
Dancer \
|
|
DBIx::Class \
|
|
DBD::Pg \
|
|
Dancer::Plugin::DBIC \
|
|
NetAddr::IP \
|
|
Net::MAC \
|
|
List::MoreUtils \
|
|
Net::DNS \
|
|
Socket6 \
|
|
HTML::Entities \
|
|
Template::Toolkit \
|
|
YAML
|
|
|
|
In case you were wondering, the vast majority of dependencies come from
|
|
L<DBIx::Class>.
|
|
|
|
B<Note> that to install L<DBD::Pg> you need the PostgreSQL development libraries
|
|
also installed. Best advice is to omit that item from the above script and try
|
|
to install a prebuilt DBD::Pg package for your OS. The following command will
|
|
test for the existence of DBD::Pg on your system:
|
|
|
|
perl -MDBD::Pg\ 999
|
|
|
|
=head1 STARTUP
|
|
|
|
There's a simple web server built-in. This is sufficient for
|
|
standalone, single-user operation and development, but does not have
|
|
performance for a production environment.
|
|
|
|
The following command initializes an environment which can access the installed
|
|
Perl modules, then starts this small web server:
|
|
|
|
~/perl-profiles/netdisco-web/bin/localenv Netdisco/bin/netdisco-web.pl
|
|
|
|
Speak to C<oliver> on IRC if you want advice on firing up the application
|
|
under Apache, FastCGI, or other environments.
|
|
|
|
=head1 TIPS AND TRICKS
|
|
|
|
The main black navigation bar has a search box which is smart enough to work
|
|
out what you're looking for in most cases. For example device names, node IP
|
|
or MAC addreses, VLAN numbers, and so on.
|
|
|
|
If you've patched your C<node_ip> table to have a cached DNS entry column
|
|
called C<dns> then uncomment the two indicated lines in C<NodeIP.pm>.
|
|
|
|
Remember you can disable authentication by changing a setting in the
|
|
configuration file, as explained above.
|
|
|
|
=head1 FUTURE WORK
|
|
|
|
At the moment the ability to just hit Enter in the title-bar Search is a
|
|
I<hack> because there's no other way to list all Inventory. When the Reports
|
|
code is added, the Inventory will be a part of that. It's understood that
|
|
simply hitting enter should return no results, not all results.
|
|
|
|
The intention is to support "plugins" for additonal features, most notably
|
|
columns in the Device Port listing, but also new menu items and tabs. The
|
|
design of this is sketched out but not implemented. The goal is to avoid
|
|
patching core code to add localizations or less widely used features. One
|
|
could imagine a C<Netdisco::Web::Plugin::> namespace for these.
|
|
|
|
Bundled with this app is a L<DBIx::Class> layer for the Netdisco database.
|
|
This could be a starting point for an "official" DBIC layer, but be warned
|
|
that at the moment it's a bit messy. Helper functions and canned searches have
|
|
been thrown together to support the web interface with little thought for
|
|
style or consistency or performance. That will come later.
|
|
|
|
=head1 CAVEATS
|
|
|
|
Some sections are not yet implemented, e.g. the Device Module tab.
|
|
|
|
Menu items on the main black navigation bar go nowhere, except Home.
|
|
|
|
None of the Reports yet exist (e.g. searching for wireless devices, or duplex
|
|
mismatches). These might be implemented as a plugin bundle.
|
|
|
|
The Wireless, IP Phone and NetBIOS Node properies are not yet shown.
|
|
|
|
When running the standalone built-in web server, it will occasionally
|
|
start to die on you. This usually manifests as returning page content
|
|
but no stylesheet. Restarting the server is the best solution.
|
|
|
|
=head1 COPYRIGHT AND LICENCE
|
|
|
|
Copyright (c) 2012, The Netdisco Developer Team.
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
* Neither the name of the Netdisco Project nor the
|
|
names of its contributors may be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE NETDISCO DEVELOPER TEAM BE LIABLE FOR ANY
|
|
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|