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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
It is divided into sections that start at markers that look like
|
It is divided into sections that start at declarations that look like
|
||||||
<code>[<replaceable>section</replaceable>]</code>.
|
<code>[<replaceable>section</replaceable>]</code>; i.e. an opening square bracket, followed
|
||||||
Comments are all line-based comments,
|
by the section name, and terminated by a closing square bracket, on a line by itself.
|
||||||
and are lines that start with '<literal>#</literal>' or '<literal>;</literal>'.
|
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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
@@ -46,40 +111,16 @@ line in the server section, like:
|
|||||||
[Server]
|
[Server]
|
||||||
Driver=curses
|
Driver=curses
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This tells <application>LCDd</application> to use the <literal>curses</literal> driver.
|
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>
|
</para>
|
||||||
|
</example>
|
||||||
<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>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The drivers read their own options from the config file.
|
The drivers read their own options from the config file.
|
||||||
For this purpose they use the config sections that are named like the driver.
|
For this purpose they use the config sections that are named like the driver.
|
||||||
</para>
|
</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">
|
<sect2 id="server-section">
|
||||||
<title id="server-section.title"><filename>LCDd.conf</filename>: The <code>[Server]</code> Section</title>
|
<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>
|
If not specified <replaceable>DRIVERPATH</replaceable>
|
||||||
defaults to the empty string, resulting in drivers being
|
defaults to the empty string, resulting in drivers being
|
||||||
searched
|
searched
|
||||||
in the directory LCDd is started in.
|
in the directory <application>LCDd</application> is started in.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
@@ -109,13 +150,25 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<command>Driver=</command>
|
<command>Driver=</command>
|
||||||
<arg choice="plain"><replaceable>DRIVERNAME</replaceable></arg>
|
<arg choice="plain"><replaceable>DRIVERNAME</replaceable></arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Tells the server which driver(s) to use. See
|
<para>
|
||||||
<link linkend="which-driver">above</link> for details.
|
Tells the server which driver(s) to use.
|
||||||
If not specified <replaceable>DRIVERNAME</replaceable>
|
The first driver specified here that is capable of output functionality
|
||||||
defaults to <literal>curses</literal>, a driver that is supposed
|
will be used as the <emphasis>master</emphasis> output driver, defining
|
||||||
to work on any half-way decent UNIX console.
|
display properties and capabilities.
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -123,11 +176,18 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<command>Bind=</command>
|
<command>Bind=</command>
|
||||||
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
|
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Tells the server to bind to the given local IP address and listen for incoming client connections.
|
<para>
|
||||||
The default value for <replaceable>ADDRESS</replaceable> is <literal>127.0.0.1</literal>, which
|
Tells the server to bind to the given local IP address and listen for incoming client connections.
|
||||||
is actually the safest variant.
|
The default value for <replaceable>ADDRESS</replaceable> is <literal>127.0.0.1</literal>, which
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -135,10 +195,16 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<command>Port=</command>
|
<command>Port=</command>
|
||||||
<arg choice="plain"><replaceable>PORTNUMBER</replaceable></arg>
|
<arg choice="plain"><replaceable>PORTNUMBER</replaceable></arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Tells the server to listen to this specified port.
|
<para>
|
||||||
If not specified <replaceable>PORTNUMBER</replaceable> defaults to <literal>13666</literal>.
|
Tells the server to listen to this specified port.
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -146,12 +212,18 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<command>ReportLevel=</command>
|
<command>ReportLevel=</command>
|
||||||
<arg choice="plain"><replaceable>LEVEL</replaceable></arg>
|
<arg choice="plain"><replaceable>LEVEL</replaceable></arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Sets the reporting level.
|
<para>
|
||||||
Legal values for <replaceable>LEVEL</replaceable> range from <literal>0</literal>
|
Sets the reporting level.
|
||||||
(only critical errors) to <literal>5</literal> (everything including debugging information).
|
Legal values for <replaceable>LEVEL</replaceable> range from <literal>0</literal>
|
||||||
If not specified it defaults to <literal>2</literal> (warnings and errors only).
|
(only critical errors) to <literal>5</literal> (everything including debugging information).
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -164,10 +236,27 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
</group>
|
</group>
|
||||||
</arg>
|
</arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Should we report to <filename>syslog</filename> instead of <filename>stderr</filename>?
|
<para>
|
||||||
Default value is <literal>no</literal>.
|
Should we report to <filename>syslog</filename> (<literal>yes</literal>)
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -177,18 +266,13 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
</term>
|
</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
User to run as. When started as root LCDd will drop its privileges,
|
User to run as. When started as root <application>LCDd</application> will drop its privileges,
|
||||||
and run as this user instead. Defaults to <literal>nobody</literal>.
|
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>
|
</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>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
@@ -202,11 +286,17 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
</group>
|
</group>
|
||||||
</arg>
|
</arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
The server will stay in the foreground if set to true.
|
<para>
|
||||||
Otherwise the server will fork to background and report
|
The server will stay in the foreground if set to true.
|
||||||
to syslog. Defaults to <literal>no</literal>.
|
Otherwise the server will fork to background and report
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -217,7 +307,7 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Define the startup message printed on the screen when LCDd starts.
|
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
|
If not given, it defaults to the builtin server screen that tells
|
||||||
how many clients are connected and how many screens these clients
|
how many clients are connected and how many screens these clients
|
||||||
are using in total.
|
are using in total.
|
||||||
@@ -279,10 +369,16 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
<command>WaitTime=</command>
|
<command>WaitTime=</command>
|
||||||
<arg choice="plain"><replaceable>SECONDS</replaceable></arg>
|
<arg choice="plain"><replaceable>SECONDS</replaceable></arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Sets the default time in seconds to display a screen.
|
<para>
|
||||||
If not specified the default value for <replaceable>SECONDS</replaceable> is <literal>4</literal>.
|
Sets the default time in seconds to display a screen.
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@@ -295,11 +391,19 @@ settings for the LCDproc server <application>LCDd</application>.
|
|||||||
</group>
|
</group>
|
||||||
</arg>
|
</arg>
|
||||||
</term>
|
</term>
|
||||||
<listitem><para>
|
<listitem>
|
||||||
Include the server screen, that shows the number of active clients and screens,
|
<para>
|
||||||
into the screen rotation scheme when other screens exist.
|
Include the server screen, that shows the number of active clients and screens,
|
||||||
Defaults to <literal>yes</literal>.
|
into the screen rotation scheme when other screens exist.
|
||||||
</para></listitem>
|
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>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
|||||||
Reference in New Issue
Block a user