diff --git a/Netdisco/lib/App/Netdisco/Manual/Configuration.pod b/Netdisco/lib/App/Netdisco/Manual/Configuration.pod new file mode 100644 index 00000000..b98b5bb4 --- /dev/null +++ b/Netdisco/lib/App/Netdisco/Manual/Configuration.pod @@ -0,0 +1,142 @@ +=head1 NAME + +App::Netdisco::Manual::Configuration - How to Configure Netdisco + +=head1 INTRODUCTION + +The configuration files for Netdisco come with all options set to sensible +default values, and just a few that you initially must set yourself. + +However as you use the system over time, there are many situations where you +might want to tune the behaviour of Netdisco, and for that we have a lot of +configuration settings available. + +=head2 GUIDANCE + +There are two configuration files: C (which lives inside Netdisco) +and C (which usually lives in C<${HOME}/environments>). + +The C file includes defaults for every setting, and should be left +alone. Any time you want to set an option, use only the C +file. The two are merged when Netdisco starts, with your settings in +C overriding the defaults from C. + +The configuration file format for Netdisco is YAML. This is easy for humans to +edit, but you should take care over whitespace and avoid TAB characters. YAML +supports several data types: + +=over 4 + +=item * + +Boolean - True/False value, using C<1> and C<0> or C and C +respectively + +=item * + +List - Set of things using C<[a, b, c]> on one line or C<-> on separate lines + +=item * + +Dictionary - Key/Value pairs (like Perl Hash) using C<{key1: val1, key2, +val2}> on one line or C on separate lines + +=item * + +String - Quoted, just like in Perl (and essential if the item contains the +colon character) + +=back + +=head1 SUPPORTED SETTINGS + +=head2 Essential Settings + +If you followed the installation instructions, then you should have set the +database connection parameters to match those of your local system. That is, +the C (DB name, host, port), C and C. + +=head2 General Settings + +=head3 C + +Default: C + +The log level used by Netdisco. It's useful to see warning messages from the +backend poller, as this can highlight broken topology. + +=head3 C + +Default: C + +Destination for log messages. Console means standard ouput. When set to +C, the default destination is the C<${HOME}/logs> directory. + +=head3 C + +Default: C<< '[%P] %L @%D> %m' >> + +Structure of the log messages. See L +for details. + +=head2 Web Frontend + +=head3 C + +Default: None + +Set this to your local site's domain name. This is usually removed from node +names in the web interface to make things more readable. + +=head3 C + +Default: C + +Enable this to disable login authentication in the web frontend. The username +will be set to C so if you want to allow extended permissions (C +or C, create a dummy user with the appropriate flag, in the +database: + + netdisco=> insert into users (username, port_control) values ('guest', true); + +=head3 C + +Default: C<5000> + +Port which the web server listens on. Netdisco comes with a good pre-forking +web server, so you can change this to C<80> if you want to use it directly. +However the default is designed to work well with servers such as Apache in +reverse-proxy mode. + +=head3 C + +Default: List of L names + +Netdisco's plugin system allows the user more control over the user interface. +Plugins can be distributed independently from Netdisco and are a better +alternative to source code patches. This setting is the list of Plugins which +are used in the default Netdisco distribution. + +You can override this to set your own list. If you only want to add to the +default list then use C, which allows the Netdisco +developers to update C in a future release. + +=head3 C + +Default: None + +List of additional L names to load. See also the +C setting. + +=head2 Netdisco Core + +=head2 Backend Daemon + +=head2 Dancer Internal + +=head1 UNSUPPORTED SETTINGS + +These settings are from Netdisco 1.x but are yet to be supported in Netdisco +2. If you really need the feature, please let the developers know. + +=cut