extend user documentation
This commit is contained in:
marschap
@@ -23,10 +23,75 @@ The format of the <filename>/etc/LCDd.conf</filename> is INI-file like.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is divided into sections that start at markers that look like
|
||||
<code>[<replaceable>section</replaceable>]</code>.
|
||||
Comments are all line-based comments,
|
||||
and are lines that start with '<literal>#</literal>' or '<literal>;</literal>'.
|
||||
It is divided into sections that start at declarations that look like
|
||||
<code>[<replaceable>section</replaceable>]</code>; i.e. an opening square bracket, followed
|
||||
by the section name, and terminated by a closing square bracket, on a line by itself.
|
||||
Section names are case insensitive.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Parameters are grouped into sections and have the form
|
||||
<code><replaceable>key</replaceable>=<replaceable>value</replaceable></code>;
|
||||
i.e. a key, also known as the configuration option, followed by an equality sign and
|
||||
finally the value for the option.
|
||||
All three elements must occur together on one line.
|
||||
The <replaceable>key</replaceable>, which is case insensitive, may be surrounded by spaces,
|
||||
but is must be one word (i.e. a sequence of non-space characters) not containing the equality sign.
|
||||
A similar rule applies to the <replaceable>value</replaceable>: it may be surrounded by spaces,
|
||||
but it must be either one word or enclosed within double quotes (<literal>"</literal>),
|
||||
which are not considered as part of <replaceable>value</replaceable>.
|
||||
When quoted, the following character sequences are evaluated as in literal C strings:
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
</thead>
|
||||
<row>
|
||||
<entry>escape sequence</entry>
|
||||
<entry>character</entry>
|
||||
</row>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>\a</literal></entry>
|
||||
<entry>alert (bell) character</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\b</literal></entry>
|
||||
<entry>backspace</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\f</literal></entry>
|
||||
<entry>formfeed</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\n</literal></entry>
|
||||
<entry>newline</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\r</literal></entry>
|
||||
<entry>carriage return</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\t</literal></entry>
|
||||
<entry>horizontal tab</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\v</literal></entry>
|
||||
<entry>vertical tab</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>\\</literal></entry>
|
||||
<entry>backslash</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
All other occurences of <literal>\</literal> within quoted values will be ignored.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Comments are all line-based, and may start with '<literal>#</literal>' or '<literal>;</literal>'.
|
||||
Everything including and behind the character starting the comment up to the end
|
||||
of the line is ignored.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -46,40 +111,16 @@ line in the server section, like:
|
||||
[Server]
|
||||
Driver=curses
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
<para>
|
||||
This tells <application>LCDd</application> to use the <literal>curses</literal> driver.
|
||||
The first driver specified here that is capable of output functionality
|
||||
will be used as <emphasis>the</emphasis> output driver.
|
||||
All other drivers can only serve as input drivers.
|
||||
The default driver to use is <literal>curses</literal>.
|
||||
</para>
|
||||
|
||||
<warning>
|
||||
<para>
|
||||
If LCDd is started automatically by an init-script using the curses driver,
|
||||
it will lock <filename>/dev/tty1</filename>! So, be careful about what you are
|
||||
doing here.
|
||||
</para>
|
||||
</warning>
|
||||
</example>
|
||||
|
||||
<para>
|
||||
The drivers read their own options from the config file.
|
||||
For this purpose they use the config sections that are named like the driver.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>LCDd -d driver</command>
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
If <option>-d</option> is specified on the command line, the
|
||||
<code>Driver=</code> options in the configuration file are ignored.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<sect2 id="server-section">
|
||||
<title id="server-section.title"><filename>LCDd.conf</filename>: The <code>[Server]</code> Section</title>
|
||||
|
||||
@@ -100,7 +141,7 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
If not specified <replaceable>DRIVERPATH</replaceable>
|
||||
defaults to the empty string, resulting in drivers being
|
||||
searched
|
||||
in the directory LCDd is started in.
|
||||
in the directory <application>LCDd</application> is started in.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
@@ -109,13 +150,25 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<command>Driver=</command>
|
||||
<arg choice="plain"><replaceable>DRIVERNAME</replaceable></arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Tells the server which driver(s) to use. See
|
||||
<link linkend="which-driver">above</link> for details.
|
||||
If not specified <replaceable>DRIVERNAME</replaceable>
|
||||
defaults to <literal>curses</literal>, a driver that is supposed
|
||||
to work on any half-way decent UNIX console.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Tells the server which driver(s) to use.
|
||||
The first driver specified here that is capable of output functionality
|
||||
will be used as the <emphasis>master</emphasis> output driver, defining
|
||||
display properties and capabilities.
|
||||
All other drivers specified can only serve as input drivers
|
||||
or slave output drivers.
|
||||
If not specified <replaceable>DRIVERNAME</replaceable>
|
||||
defaults to <literal>curses</literal>, a driver that is supposed
|
||||
to work on any half-way decent UNIX console.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-d <replaceable>DRIVER</replaceable></option> option.
|
||||
When the command line option is used, only the one driver given there
|
||||
will be loaded, and all drivers specified in the configuration file are ignored.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -123,11 +176,18 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<command>Bind=</command>
|
||||
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Tells the server to bind to the given local IP address and listen for incoming client connections.
|
||||
The default value for <replaceable>ADDRESS</replaceable> is <literal>127.0.0.1</literal>, which
|
||||
is actually the safest variant.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Tells the server to bind to the given local IP address and listen for incoming client connections.
|
||||
The default value for <replaceable>ADDRESS</replaceable> is <literal>127.0.0.1</literal>, which
|
||||
is actually the safest variant, as it allows connections only from the local machine and forbids
|
||||
connections from remote systems.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-a <replaceable>ADDRESS</replaceable></option> option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -135,10 +195,16 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<command>Port=</command>
|
||||
<arg choice="plain"><replaceable>PORTNUMBER</replaceable></arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Tells the server to listen to this specified port.
|
||||
If not specified <replaceable>PORTNUMBER</replaceable> defaults to <literal>13666</literal>.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Tells the server to listen to this specified port.
|
||||
If not specified <replaceable>PORTNUMBER</replaceable> defaults to <literal>13666</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-p <replaceable>PORTNUMBER</replaceable></option> option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -146,12 +212,18 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<command>ReportLevel=</command>
|
||||
<arg choice="plain"><replaceable>LEVEL</replaceable></arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Sets the reporting level.
|
||||
Legal values for <replaceable>LEVEL</replaceable> range from <literal>0</literal>
|
||||
(only critical errors) to <literal>5</literal> (everything including debugging information).
|
||||
If not specified it defaults to <literal>2</literal> (warnings and errors only).
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the reporting level.
|
||||
Legal values for <replaceable>LEVEL</replaceable> range from <literal>0</literal>
|
||||
(only critical errors) to <literal>5</literal> (everything including debugging information).
|
||||
If not specified it defaults to <literal>2</literal> (warnings and errors only).
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-r <replaceable>LEVEL</replaceable></option> option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -164,10 +236,27 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
</group>
|
||||
</arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Should we report to <filename>syslog</filename> instead of <filename>stderr</filename>?
|
||||
Default value is <literal>no</literal>.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Should we report to <filename>syslog</filename> (<literal>yes</literal>)
|
||||
instead of <filename>stderr</filename> (<literal>no</literal>)?
|
||||
Default value is <literal>no</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-s <replaceable>NUMBER</replaceable></option> option.
|
||||
Passing <option>-s 1</option> on the command line enables reporting to <filename>syslog</filename>
|
||||
while <option>-s 0</option> disables it.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
If <application>LCDd</application> is started automatically by an init script
|
||||
using the <literal>curses</literal> driver, it will lock <filename>/dev/tty1</filename>!
|
||||
So, be careful about what you are doing here.
|
||||
</para>
|
||||
</warning>
|
||||
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -177,18 +266,13 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
User to run as. When started as root LCDd will drop its privileges,
|
||||
and run as this user instead. Defaults to <literal>nobody</literal>.
|
||||
User to run as. When started as root <application>LCDd</application> will drop its privileges,
|
||||
and run as <replaceable>USER</replaceable> instead. Defaults to <literal>nobody</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-u <replaceable>USER</replaceable></option> option.
|
||||
</para>
|
||||
<!--
|
||||
<note>
|
||||
<para>
|
||||
If you want to use the server menu, to shutdown or reboot your system,
|
||||
you will have to set this to root. Otherwise LCDd does not have the
|
||||
privileges to run commands like <command>init 6</command>.
|
||||
</para>
|
||||
</note>
|
||||
-->
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
@@ -202,11 +286,17 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
</group>
|
||||
</arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
The server will stay in the foreground if set to true.
|
||||
Otherwise the server will fork to background and report
|
||||
to syslog. Defaults to <literal>no</literal>.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The server will stay in the foreground if set to true.
|
||||
Otherwise the server will fork to background and report
|
||||
to syslog. Defaults to <literal>no</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line with the <option>-f</option> option that forces foreground mode.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -217,7 +307,7 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<listitem>
|
||||
<para>
|
||||
Define the startup message printed on the screen when LCDd starts.
|
||||
This message will stay on the screen until a client connects.
|
||||
This message will stay on the screen until the first client connects.
|
||||
If not given, it defaults to the builtin server screen that tells
|
||||
how many clients are connected and how many screens these clients
|
||||
are using in total.
|
||||
@@ -279,10 +369,16 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
<command>WaitTime=</command>
|
||||
<arg choice="plain"><replaceable>SECONDS</replaceable></arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Sets the default time in seconds to display a screen.
|
||||
If not specified the default value for <replaceable>SECONDS</replaceable> is <literal>4</literal>.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the default time in seconds to display a screen.
|
||||
If not specified the default value for <replaceable>SECONDS</replaceable> is <literal>4</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line with the <option>-w <replaceable>SECONDS</replaceable></option> option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@@ -295,11 +391,19 @@ settings for the LCDproc server <application>LCDd</application>.
|
||||
</group>
|
||||
</arg>
|
||||
</term>
|
||||
<listitem><para>
|
||||
Include the server screen, that shows the number of active clients and screens,
|
||||
into the screen rotation scheme when other screens exist.
|
||||
Defaults to <literal>yes</literal>.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Include the server screen, that shows the number of active clients and screens,
|
||||
into the screen rotation scheme when other screens exist.
|
||||
Defaults to <literal>yes</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This setting can be overridden on <application>LCDd</application>'s
|
||||
command line using the <option>-i <replaceable>NUMBER</replaceable></option> option.
|
||||
Passing <option>-i 1</option> on the command line enables server screen rotation,
|
||||
while <option>-i 0</option> disables it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
|
||||
Reference in New Issue
Block a user