diff --git a/README b/README index 551fdc1..0df88af 100644 --- a/README +++ b/README @@ -1,3 +1,6 @@ + +This is the BIP IRC Proxy readme, you'll learn how to quickly use bip. + Bip can be used in two different way: - Old school bnc user style: easy and straightforward. - Unix service style with and init.d scripts and the logs in /var/log @@ -7,47 +10,116 @@ This small README file explains the usage "Old school" with which : - gives easy access to the logs of the users of this bip to the one owning the shell. -Install bip on the machine that will be running bip (which is likely to be your -personnal or shared server) either compiling the package or using your distro's -package. Then create a configuration file: +Table of contents : -If you are using a distribution package, the bip.conf sample configuration file -is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or something -similar. + I. Installation + II. Configuration + A. Manual configuration + B. Automated configuration + III. Running bip + IV. Using bip -Create your bip configuration an log directory: -# mkdir -p ~/.bip/logs -Put the uncompressed configuration file in your ~/.bip directory (it's path -should be ~/.bip/bip.conf), and edit it, most importantly the "user" section -that contains information about you and the servers you will want to connect -to. The "name" field in the "user" section is your login to connect to bip. -The "password" field is a hash of the password you will use to connect to bip. -To generate a hash value from a password, use bipmkpw, program which comes in -the bip package and source. -The "name" field of the "connection" subsections are the server identifier for -when you connect to bip. +I. INSTALLATION -Once all this is configured, start bip as you regular user: + Install bip on the machine that will be running bip (which is likely to be + your personnal or shared server) either compiling the package or using your + distro's package. Then create a configuration file. + -# bip +II. CONFIGURATION -Once bip starts, it connects to the different servers your defined in -"connection". Then you want to use your regular irc client and connect to bip. -Point your client to the machine bip is running and set the proper port number -(defined in your bip.conf). You should then configure the client to use a -specific irc server password constructed this way: + First of all, create your bip configuration an log directory: + + # mkdir -p ~/.bip/logs + + There are two ways to create your bip configuration : + - edit the sample bip.conf file to match your needs + - use the bipgenconfig script to easily generate a configuration + + If you want to connect to bip using an SSL client, you'll need to create + a certificate / key pair (in a bip.pem file) to allow bip to serve SSL + sockets. -user:password:network + A. MANUAL CONFIGURATION -The user is the name field of the "user" section, the password is the password -(*not* the hash) corresponding to the "password" field of the same user section -(which is the hash generated with bipmkpw) and the network is the "name" field -of the "connection" subsection. This is how bip authenticates you and puts your -client to the correct network. + If you are using a distribution package, the bip.conf sample configuration + file is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or + something similar. + + If not, you'll find sample configuration file in the source package's + `samples' subdirectory. + + Put the uncompressed configuration file in your ~/.bip directory (it's + path should be ~/.bip/bip.conf), and edit it, most importantly the "user" + section that contains information about you and the servers you will want + to connect to. The "name" field in the "user" section is your login to + connect to bip. + The "name" field of the "connection" subsections are the server identifier + for when you connect to bip. -Using the default (or sample file) configuration, logs are in ~/.bip/logs/ + The "password" field is a hash of the password you will use to connect to + bip. To generate a hash value from a password, use bipmkpw, program which + comes in the bip package and source. -Happy ircing! + If you've set client_side_ssl to true, you'll need to generate a bip.pem + file containing a certificate / key pair. In order to do so, you can use + the third party `openssl' binary : + # openssl req -new -x509 -days 365 -nodes -out bip.pem -keyout bip.pem + + You can then remove the passphrase with : + + # openssl x509 -subject -dates -fingerprint -noout -in bip.pem + + B. AUTOMATED CONFIGURATION + + You can also use the bipgenconfig script to generate a new configuration. + This script will also help you generate the SSL certificate / key pair + needed for clients to connect to BIP through SSL. + + This script can be found either in the source package's `scripts' + directory or shipped with your distribution's package. + + Using the script is very simple, and it'll generate a configuration file + but won't overwrite any existing configuration. + + It'll ask you the path to the bipmkpw binary, to automatically hash the + passwords you'll provide. Please make sure to enter the correct path to + the binary or you might observe unexpected behaviour. + + You'll need to move the generated configuration from bip.conf.autogen to + bip.conf and the generated PEM file from bip.pem.autogen to bip.pem (or + whatever path you've configured in bip.conf). + + +III. RUNNING BIP + + Once all this is configured, start bip as your regular user: + + # bip + + Once bip starts, it connects to the different servers your defined in + all "user"'s "connection" blocks. + + +IV. USING BIP + + Then you want to use your regular irc client and connect to bip. + Point your client to the machine bip is running and set the proper port number + (defined in your bip.conf). You should then configure the client to use a + specific irc server password constructed this way: + + user:password:network + + The user is the name field of the "user" section, the password is the password + (*not* the hash) corresponding to the "password" field of the same user section + (which is the hash generated with bipmkpw) and the network is the "name" field + of the "connection" subsection. This is how bip authenticates you and puts your + client to the correct network. + + Using the default (or sample file) configuration, logs are in ~/.bip/logs/ + + Happy ircing! + diff --git a/bip.conf.1 b/bip.conf.1 index 15a6def..4f8396c 100644 --- a/bip.conf.1 +++ b/bip.conf.1 @@ -102,7 +102,12 @@ change, nick change, user quit/part/join will be backlogged upon connection. \fBclient_side_ssl\fP (default: \fBfalse\fP) When true, clients will need to connect to BIP using SSL. You'll also need to generate a SSL cert/key pair in /bip.pem (usually -~bip/.bip/bip.pem or /var/lib/bip/bip.pem). +~bip/.bip/bip.pem or /var/lib/bip/bip.pem) or if defined. + +.TP +\fBclient_side_ssl_pem\fP (default: \fB/bip.pem\fP) +Set this to the full path of the cert/key pair bip should use to accept clients +SSL connections. .TP \fBip\fP diff --git a/samples/bip.conf b/samples/bip.conf index 5faa8e9..4b86e31 100644 --- a/samples/bip.conf +++ b/samples/bip.conf @@ -18,7 +18,7 @@ client_side_ssl = false; # This is the file containing the SSL cert/key pair bip'll use to # serve SSL clients. If unset, it defaults to /bip.pem -#client_side_ssl_key = "/path/to/pemfile"; +#client_side_ssl_pem = "/path/to/pemfile"; log_level = 3; diff --git a/samples/bip.vim b/samples/bip.vim index 9f761ef..57bb2f2 100644 --- a/samples/bip.vim +++ b/samples/bip.vim @@ -54,7 +54,7 @@ syn region bipMain start=/\%^/ end=/\%$/ " Top level elements syn keyword bipKeyword contained nextgroup=bipBoolV client_side_ssl syn keyword bipKeyword contained nextgroup=bipStringV log_root - \ log_format pid_file client_side_ssl_key + \ log_format pid_file client_side_ssl_pem syn keyword bipKeyword contained nextgroup=bipNumericV port log_level \ log_sync_interval syn keyword bipKeyword contained nextgroup=bipIPV ip diff --git a/scripts/bipgenconfig b/scripts/bipgenconfig index ad58e97..74f036e 100755 --- a/scripts/bipgenconfig +++ b/scripts/bipgenconfig @@ -46,6 +46,9 @@ my %optdesc = ( 'client_side_ssl' => { 'type' => 'b', 'adv' => 1, 'default' => 'true', 'optional' => 1, 'desc' => 'Do you want to enable client side SSL ?' }, + 'client_side_ssl_pem' => { 'type' => 's', 'adv' => 1, 'optional' => 1, + 'default' => '', + 'desc' => 'Where is the bip.pem file (cert/key pair) ?' }, 'pid_file' => { 'type' => 's', 'adv' => 1, 'optional' => 1, 'default' => $bipdir . '/bip.pid', 'desc' => 'Where do you want the pidfile to be stored ?' }, @@ -216,6 +219,7 @@ my %optorder = ( 'ip' , 'port' , 'client_side_ssl' , + 'client_side_ssl_pem' , 'pid_file' , undef, 'log' , diff --git a/src/bip.c b/src/bip.c index 26e80ec..5769b18 100644 --- a/src/bip.c +++ b/src/bip.c @@ -968,12 +968,12 @@ int fireup(bip_t *bip, FILE *conf) case LEX_CSS: conf_css = t->ndata; break; - case LEX_CSS_KEY: + case LEX_CSS_PEM: MOVE_STRING(conf_ssl_certfile, t->pdata); break; #else case LEX_CSS: - case LEX_CSS_KEY: + case LEX_CSS_PEM: mylog(LOG_WARN, "Found SSL option whereas bip is " "not built with SSL support."); break; diff --git a/src/conf.y b/src/conf.y index a902f50..83161cd 100644 --- a/src/conf.y +++ b/src/conf.y @@ -68,7 +68,7 @@ struct tuple *tuple_l_new(int type, void *p) %} -%token LEX_IP LEX_EQ LEX_PORT LEX_CSS LEX_SEMICOLON LEX_CONNECTION LEX_NETWORK LEX_LBRA LEX_RBRA LEX_USER LEX_NAME LEX_NICK LEX_SERVER LEX_PASSWORD LEX_SRCIP LEX_HOST LEX_VHOST LEX_SOURCE_PORT LEX_NONE LEX_COMMENT LEX_BUNCH LEX_REALNAME LEX_SSL LEX_SSL_CHECK_MODE LEX_SSL_CHECK_STORE LEX_CHANNEL LEX_KEY LEX_LOG_ROOT LEX_LOG_FORMAT LEX_LOG_LEVEL LEX_BACKLOG_LINES LEX_BACKLOG_NO_TIMESTAMP LEX_BACKLOG LEX_LOG LEX_LOG_SYSTEM LEX_LOG_SYNC_INTERVAL LEX_FOLLOW_NICK LEX_ON_CONNECT_SEND LEX_AWAY_NICK LEX_PID_FILE LEX_IGN_FIRST_NICK LEX_ALWAYS_BACKLOG LEX_BLRESET_ON_TALK LEX_DEFAULT_USER LEX_DEFAULT_NICK LEX_DEFAULT_REALNAME LEX_NO_CLIENT_AWAY_MSG LEX_BL_MSG_ONLY LEX_ADMIN LEX_BIP_USE_NOTICE LEX_CSS_KEY +%token LEX_IP LEX_EQ LEX_PORT LEX_CSS LEX_SEMICOLON LEX_CONNECTION LEX_NETWORK LEX_LBRA LEX_RBRA LEX_USER LEX_NAME LEX_NICK LEX_SERVER LEX_PASSWORD LEX_SRCIP LEX_HOST LEX_VHOST LEX_SOURCE_PORT LEX_NONE LEX_COMMENT LEX_BUNCH LEX_REALNAME LEX_SSL LEX_SSL_CHECK_MODE LEX_SSL_CHECK_STORE LEX_CHANNEL LEX_KEY LEX_LOG_ROOT LEX_LOG_FORMAT LEX_LOG_LEVEL LEX_BACKLOG_LINES LEX_BACKLOG_NO_TIMESTAMP LEX_BACKLOG LEX_LOG LEX_LOG_SYSTEM LEX_LOG_SYNC_INTERVAL LEX_FOLLOW_NICK LEX_ON_CONNECT_SEND LEX_AWAY_NICK LEX_PID_FILE LEX_IGN_FIRST_NICK LEX_ALWAYS_BACKLOG LEX_BLRESET_ON_TALK LEX_DEFAULT_USER LEX_DEFAULT_NICK LEX_DEFAULT_REALNAME LEX_NO_CLIENT_AWAY_MSG LEX_BL_MSG_ONLY LEX_ADMIN LEX_BIP_USE_NOTICE LEX_CSS_PEM %union { int number; @@ -97,7 +97,7 @@ command: | LEX_IP LEX_EQ LEX_STRING { $$ = tuple_s_new(LEX_IP, $3); } | LEX_PORT LEX_EQ LEX_INT { $$ = tuple_i_new(LEX_PORT, $3); } | LEX_CSS LEX_EQ LEX_BOOL { $$ = tuple_i_new(LEX_CSS, $3); } - | LEX_CSS_KEY LEX_EQ LEX_STRING { $$ = tuple_s_new(LEX_CSS_KEY, $3); } + | LEX_CSS_PEM LEX_EQ LEX_STRING { $$ = tuple_s_new(LEX_CSS_PEM, $3); } | LEX_LOG LEX_EQ LEX_BOOL { $$ = tuple_i_new(LEX_LOG, $3); } | LEX_LOG_SYSTEM LEX_EQ LEX_BOOL { $$ = tuple_i_new(LEX_LOG_SYSTEM, $3); } | LEX_LOG_SYNC_INTERVAL LEX_EQ LEX_INT { $$ = tuple_i_new( diff --git a/src/lex.l b/src/lex.l index 081794f..8516068 100644 --- a/src/lex.l +++ b/src/lex.l @@ -111,7 +111,7 @@ list_t *parse_conf(FILE *file, int *err) "no_client_away_msg" { return LEX_NO_CLIENT_AWAY_MSG; } "pid_file" { return LEX_PID_FILE; } "bip_use_notice" { return LEX_BIP_USE_NOTICE; } -"client_side_ssl_key" { return LEX_CSS_KEY; } +"client_side_ssl_pem" { return LEX_CSS_PEM; } \"[^"]*\" { size_t len = strlen(yytext) - 2; yylval.string = malloc(len + 1);