Merge commit 'kyo/pemfile_option'

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
+Table of contents :
-personnal or shared server) either compiling the package or using your distro's
-package. Then create a configuration file:
 
-If you are using a distribution package, the bip.conf sample configuration file
+	I.	Installation
-is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or something
+	II.	Configuration
-similar.
+	   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
+I. INSTALLATION
-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.
 
-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
+    First of all, create your bip configuration an log directory:
-"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
+    # mkdir -p ~/.bip/logs
-(defined in your bip.conf). You should then configure the client to use a
+    
-specific irc server password constructed this way:
+    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
+      If you are using a distribution package, the bip.conf sample configuration
-(*not* the hash) corresponding to the "password" field of the same user section
+      file is likely to be shipped in /usr/share/doc/bip/examples/bip.conf.gz or
-(which is the hash generated with bipmkpw) and the network is the "name" field
+      something similar.
-of the "connection" subsection. This is how bip authenticates you and puts your
+      
-client to the correct network.
+      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!
+    

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 <bipdir>/bip.pem (usually
-~bip/.bip/bip.pem or /var/lib/bip/bip.pem).
+~bip/.bip/bip.pem or /var/lib/bip/bip.pem) or <client_side_ssl_pem> if defined.
+
+.TP
+\fBclient_side_ssl_pem\fP (default: \fB<bipdir>/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

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 <biphome>/bip.pem
-#client_side_ssl_key = "/path/to/pemfile";
+#client_side_ssl_pem = "/path/to/pemfile";
 
 log_level = 3;
 

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

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' ,

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;

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(

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);