1
0
forked from bip/bip

bip.conf manpage: improve formatting

- follow man-pages conventions
- HTML output produced by groff is more readable
This commit is contained in:
Pierre-Louis Bonicoli 2017-02-28 16:11:19 +01:00 committed by Pierre-Louis Bonicoli
parent cdbf22cdb7
commit 072a17b55b
Signed by untrusted user: pilou
GPG Key ID: ADC2651DDACD3538

View File

@ -1,4 +1,4 @@
.TH BIP.CONF 5 "04 July 2016" .TH BIP.CONF 5 "23 February 2017"
.SH NAME .SH NAME
@ -16,9 +16,11 @@ sections. It contains the global options, networks definitions, users
configuration, users connections declarations. Each section is described in configuration, users connections declarations. Each section is described in
this manpage. this manpage.
The bip.conf skeleton should be something like this : The
.BR bip.conf
skeleton should be something like this :
.nf .EX
option1 = value; option1 = value;
option2 = value; option2 = value;
... ...
@ -47,24 +49,25 @@ user {
... ...
}; };
}; };
.fi .EE
.SH SYNTAX RULES .SH SYNTAX RULES
The syntax is quite simple : The syntax is quite simple :
.br .RS
\- everything after the \fB#\fP character is ignored (comments) .IP \(bu 4
.br everything after the \fB#\fP character is ignored (comments)
\- each variable affectation must be finished with a \fB;\fP .IP \(bu 4
.br each variable affectation must be finished with a \fB;\fP
\- each section { } must be finished with a \fB;\fP .IP \(bu 4
.br each section { } must be finished with a \fB;\fP
.RE
If you use vim you will probably want to use vim with the provided If you use vim you will probably want to use vim with the provided
\fBbip.vim\fP syntax file to avoid common syntax and lexical mistakes. You can \fBbip.vim\fP syntax file to avoid common syntax and lexical mistakes. You can
also find an example configuration file along with BIP. also find an example configuration file along with BIP.
By default, \fBbipdir\fR is the \fB$HOME/.bip\fP directory and the parent By default, \fBbipdir\fR is the \fI$HOME/.bip\fR directory and the parent
directory for client certificate, configuration, logs, pid, oidentd. If directory for client certificate, configuration, logs, pid, oidentd. If
environment variable \fB$HOME\fP doesn't exist, \fB-s\fP parameter must be environment variable \fB$HOME\fP doesn't exist, \fB-s\fP parameter must be
used. used.
@ -74,12 +77,12 @@ used.
.TP .TP
\fBclient_side_ssl\fP (default: \fBfalse\fP) \fBclient_side_ssl\fP (default: \fBfalse\fP)
When true, clients will need to connect to BIP using SSL. When true, clients will need to connect to BIP using SSL.
You'll also need to generate a SSL cert/key pair in \fBbipdir\fR/bip.pem You'll also need to generate a SSL cert/key pair in \fIbipdir/bip.pem\fR
(usually ~/.bip/bip.pem or /var/lib/bip/bip.pem) or <client_side_ssl_pem> if (usually \fI~/.bip/bip.pem\fR or \fI/var/lib/bip/bip.pem\fR) or \fBclient_side_ssl_pem\fP if
defined. defined.
.TP .TP
\fBclient_side_ssl_pem\fP (default: \fB<bipdir>/bip.pem\fP) \fBclient_side_ssl_pem\fP (default: \fI<bipdir>/bip.pem\fR)
Set this to the full path of the cert/key pair bip should use to accept clients Set this to the full path of the cert/key pair bip should use to accept clients
SSL connections. SSL connections.
@ -89,7 +92,7 @@ OpenSSL cipher lists used for clients SSL connections. If not set, OpenSSL
default ciphers will be used. default ciphers will be used.
.TP .TP
\fBclient_side_dh_param\fP DH parameters filename\fP (default: \fB<bipdir>/dh.pem\fP) \fBclient_side_dh_param\fP DH parameters filename\fP (default: \fI<bipdir>/dh.pem\fR)
Used for clients SSL connections, Supply at least 2048-bit parameters. Used for clients SSL connections, Supply at least 2048-bit parameters.
.TP .TP
@ -109,15 +112,16 @@ file. Backlog is then stored into memory.
.TP .TP
\fBlog_system\fP (default: \fBtrue\fP) \fBlog_system\fP (default: \fBtrue\fP)
When true, system messages such as connection errors are logged. Else, BIP will not write system logs. When true, system messages such as connection errors are logged. Else, BIP will
not write system logs.
.TP .TP
\fBlog_format\fP (default: \fB%u/%n/%Y-%m/%c.%d.log\fP) \fBlog_format\fP (default: \fB%u/%n/%Y-%m/%c.%d.log\fP)
Determines the log file name depending on : Determines the log filename depending on :
.br .br
\- %u username (name in user { }; section) \- %u username (name in \fBuser\fP { }; section)
.br .br
\- %n network name (name in connection { }; section) \- %n network name (name in \fBconnection\fP { }; section)
.br .br
\- %c channel name \- %c channel name
.br .br
@ -132,7 +136,7 @@ Determines the log file name depending on :
Specify the verbosity of BIP from 0 (fatal errors) to 6 (huge debug output) Specify the verbosity of BIP from 0 (fatal errors) to 6 (huge debug output)
.TP .TP
\fBlog_root\fP (default: \fB<bipdir>/logs\fP) \fBlog_root\fP (default: \fI<bipdir>/logs\fR
Main log directory. Sub-directories and files will be created from there Main log directory. Sub-directories and files will be created from there
depending on \fBlog_format\fP. depending on \fBlog_format\fP.
@ -148,12 +152,12 @@ The delay increases with the number of attempts:
delay = reconn_timer * number of attempts delay = reconn_timer * number of attempts
.TP .TP
\fBpid_file\fP (default: \fB<bipdir>/bip.pid\fP) \fBpid_file\fP (default: \fI<bipdir>/bip.pid\fR)
Defines the file where BIP's pid will be stored. BIP checks if this file exists Defines the file where BIP's pid will be stored. BIP checks if this file exists
and if the pid is still alive upon startup. If true, BIP refuses to start. and if the pid is still alive upon startup. If true, BIP refuses to start.
.TP .TP
\fBoidentd_file\fP (default: \fB<bipdir>/.oidentd.conf\fP) \fBoidentd_file\fP (default: \fI<bipdir>/.oidentd.conf\fR)
oidentd configuration file (if oidentd enabled). oidentd configuration file (if oidentd enabled).
.TP .TP
@ -168,18 +172,18 @@ sections. It may appear more than once in the configuration file.
.TP .TP
\fBssl\fP (default: \fBfalse\fP) \fBssl\fP (default: \fBfalse\fP)
If true, BIP will connect to this network using SSL only. You cannot mix If true, BIP will connect to this network using SSL only. You cannot mix
SSL servers and non-SSL servers in the same network section. This is by choice, SSL servers and non-SSL servers in the same \fBnetwork\fP section. This is by choice,
we believe it's a bad idea. we believe it's a bad idea.
.TP .TP
\fBssl_ciphers\fP (override global ssl_default_ciphers) \fBssl_ciphers\fP (override global \fBssl_default_ciphers\fP)
OpenSSL cipher lists used for this network. OpenSSL cipher lists used for this network.
.TP .TP
\fBname\fP \fBname\fP
It's the network name used in the \fBconnection section\fP. Please note that It's the network name used in the \fBconnection\fP section. Please note that
this value is not used in \fBlog_format\fP, since it uses the variable this value is not used in \fBlog_format\fP, since it uses the variable
\fBname\fP from the \fBconnection section\fP. \fBname\fP from the \fBconnection\fP section.
.SH SERVER SUB-SECTION .SH SERVER SUB-SECTION
@ -202,7 +206,7 @@ options. It may appear more than once in the configuration file.
.TP .TP
\fBadmin\fP (default: \fBfalse\fP) \fBadmin\fP (default: \fBfalse\fP)
If a user has admin set to true, he'll become a bip administrator, which allows If a user has admin set to true, he'll become a bip administrator, which allows
him for example to RELOAD bip from IRC or to see the user configuration. him for example to reload bip from IRC or to see the user configuration.
.TP .TP
\fBbacklog\fP (default: \fBtrue\fP) \fBbacklog\fP (default: \fBtrue\fP)
@ -216,7 +220,7 @@ they were already sent before. That means :
If \fBbacklog_always\fP is false, backlog will be reset whenever there If \fBbacklog_always\fP is false, backlog will be reset whenever there
is no more client connected to a network. Else backlog will not be reset. is no more client connected to a network. Else backlog will not be reset.
This option should of course not be enabled if \fBbacklog_lines\fP is 0 ! This option should of course not be enabled if \fBbacklog_lines\fP is 0 !
If you still want to do so, don't forget to /BIP BLRESET sometimes. If you still want to do so, don't forget to \fB/BIP BLRESET\fP sometimes.
.TP .TP
\fBbacklog_lines\fP (default: \fB10\fP) \fBbacklog_lines\fP (default: \fB10\fP)
@ -251,26 +255,26 @@ change, nick change, user quit/part/join will be backlogged upon connection.
\fBbip_use_notice\fP (default: \fBfalse\fP) \fBbip_use_notice\fP (default: \fBfalse\fP)
If \fBbip_use_notice\fP is true, bip's notifications to the clients will be If \fBbip_use_notice\fP is true, bip's notifications to the clients will be
send as notices instead of private messages. For example, this setting applies send as notices instead of private messages. For example, this setting applies
to disconnection notifications or /BIP command replies. to disconnection notifications or \fB/BIP\fP command replies.
.TP .TP
\fBdefault_nick\fP \fBdefault_nick\fP
The default nick option for each \fBconnection section\fP where no \fBnick\fP The default nick option for each \fBconnection\fP section where no \fBnick\fP
is defined. See \fBCONNECTION SECTION\fP for more details. is defined. See \fBCONNECTION SECTION\fP for more details.
.TP .TP
\fBdefault_realname\fP \fBdefault_realname\fP
The default realname option for each \fBconnection section\fP where no The default realname option for each \fBconnection\fP section where no
\fBrealname\fP is defined. See \fBCONNECTION SECTION\fP for more details. \fBrealname\fP is defined. See \fBCONNECTION SECTION\fP for more details.
.TP .TP
\fBdefault_user\fP \fBdefault_user\fP
The default user option for each \fBconnection section\fP where no \fBuser\fP The default user option for each \fBconnection\fP section where no \fBuser\fP
is defined. See \fBCONNECTION SECTION\fP for more details. is defined. See \fBCONNECTION SECTION\fP for more details.
.TP .TP
\fBname\fP \fBname\fP
The user name. It'll be used to authenticate to bip and in \fBlog_format\fP. The username. It'll be used to authenticate to bip and in \fBlog_format\fP.
.TP .TP
\fBpassword\fP \fBpassword\fP
@ -307,8 +311,8 @@ use this feature.
.SH CONNECTION SUB-SECTION .SH CONNECTION SUB-SECTION
Each connection section associates a user to the networks he wants to connect Each \fBconnection\fP section associates a user to the networks he wants to connect
to. Thus, it must be declared in the user sections, and can be used more than to. Thus, it must be declared in the \fBUser\fP sections, and can be used more than
once. once.
.TP .TP
@ -361,7 +365,7 @@ When \fBfalse\fP, no log file is written, logs are kept in memory.
.TP .TP
\fBnick\fP \fBnick\fP
BIP will send that string as your nickname upon connect. If not specified BIP will send that string as your nickname upon connect. If not specified
and if \fBdefault_nickname\fP is specified in the \fBuser section\fP, BIP will and if \fBdefault_nickname\fP is specified in the \fBuser\fP section, BIP will
use that default nickname string. use that default nickname string.
.TP .TP
@ -371,14 +375,14 @@ server. It'd be useful for a greet on connect or to send your NickServ password.
.TP .TP
\fBpassword\fP \fBpassword\fP
This is the irc server password, which is sent upon connection to the irc server This is the IRC server password, which is sent upon connection to the IRC server
only. only.
.TP .TP
\fBrealname\fP \fBrealname\fP
BIP will send that string as the realname part (description in whois result) BIP will send that string as the realname part (description in whois result)
upon connect. If not specified and if \fBdefault_realname\fP is specified in upon connect. If not specified and if \fBdefault_realname\fP is specified in
the \fBuser section\fP, BIP will use that default realname string. the \fBuser\fP section, BIP will use that default realname string.
.TP .TP
\fBsource_port\fP \fBsource_port\fP
@ -386,13 +390,13 @@ If specified, tells BIP to connect from this port to the IRC server.
.TP .TP
\fBssl_check_mode\fP (default: \fBthe user's option\fP) \fBssl_check_mode\fP (default: \fBthe user's option\fP)
See \fBssl_check_mode\fP option in User options. See \fBssl_check_mode\fP option in \fBUser\fP section.
.TP .TP
\fBuser\fP \fBuser\fP
BIP will send that string as the user part (usually between ! and @ in a whois BIP will send that string as the user part (usually between ! and @ in a whois
result) upon connect. It's also used by the oidentd support (if enabled). If result) upon connect. It's also used by the oidentd support (if enabled). If
not specified and if \fBdefault_user\fP is specified in the \fBuser section\fP, not specified and if \fBdefault_user\fP is specified in the \fBuser\fP section,
BIP will use that default user string. BIP will use that default user string.
.TP .TP
@ -405,8 +409,8 @@ to people who only have one IP address.
.SH CHANNEL SUB-SUB-SECTION .SH CHANNEL SUB-SUB-SECTION
This section defines the list of channels to join for a user on a particular This section defines the list of channels to join for a user on a particular
network. It is to be found in the connection sections and appear more than once network. It is to be found in the \fBconnection\fP sections and appear more than once
in a connection section. in a \fBconnection\fP section.
.TP .TP
\fBname\fP \fBname\fP
@ -419,7 +423,8 @@ The channel key if needed.
.TP .TP
\fBbacklog\fP (default: \fBtrue\fP) \fBbacklog\fP (default: \fBtrue\fP)
Enable or disable backlogging of this particular channel. Enable or disable backlogging of this particular channel.
Setting this to true will NOT enable the backlog system, see the User section. Setting this to true will NOT enable the backlog system, see the \fBuser\fP
section.
.SH IRC CLIENT CONFIGURATION .SH IRC CLIENT CONFIGURATION
.P .P
@ -441,7 +446,8 @@ connectionname is the \fIname\fR defined in \fIconnection\fR sub-section.
.SH SEE ALSO .SH SEE ALSO
bip, bipmkpw .BR bip (1),
.BR bipmkpw (1)
.SH AUTHOR .SH AUTHOR