Note: This web site is only kept up to date for OSG Software 1.2 (VDT 2.0.0). If you are looking for information for the most recent release, the RPM-based OSG Software 3.0, please see the OSG documentation web site

Stunnel

What is Stunnel

Stunnel is a program that allows you to encrypt arbitrary TCP connections inside SSL. Stunnel is included in the VDT to be used in conjunction with Syslog-ng to encrypt log files. For more information, see www.stunnel.org.

The VDT includes a configuration script that will help to setup Stunnel and Syslog-ng. Typical usage instructions are shown below, for more documentation, see here.

Stunnel and certificates

Stunnel requires the use of certificates on both the client and the server to verify the hosts that are being sent to or received from. The configure_stunnel script uses the http public certificate, which is located at /etc/grid-security/http/httpcert.pem. On the client, it is necessary to get a copy of the server's http public cert. On the server, it is necessary to have a copy of each client's http public cert. After the certificates have been distributed, instructions on finishing the Stunnel/Syslog-ng setup are below.

Stunnel/Syslog-ng client setup

1. Get http public certificate from server. Put it at $VDT_LOCATION/stunnel/syslog-ng-server.pem
2. Run configure_stunnel to setup Stunnel and Syslog-ng
   Note: When running Syslog-ng through Stunnel, the central reporting host for Syslog-ng needs to point at the locally running stunnel. The --setup-syslog-ng flag will modify the syslog-ng configuration ($VDT_LOCATION/syslog-ng/etc/syslog-ng.conf) in order to set this up.

   cd $VDT_LOCATION
   . setup.[c]sh
   # SERVER_HOSTNAME is the name of the server you want to report to
   vdt/setup/configure_stunnel --setup-client --host SERVER_HOSTNAME --ca-file stunnel/syslog-ng-server.pem --setup-syslog-ng
   # Enable Stunnel.  The --server flag tells Stunnel to be started with vdt-control.
   vdt/setup/configure_stunnel --server y
   
   # After this, to start services, use vdt-control
   vdt-control --on stunnel
   vdt-control --on syslog-ng
   

3. Optional - testing Syslog-ng and Stunnel
   Here is a way to force a message across to the server in order to test your Syslog-ng w/ Stunnel configuration. Examine your Syslog-ng configuration (located at $VDT_LOCATION/syslog-ng/etc/syslog-ng.conf):

   # The first two lines should already be in your syslog-ng.conf file
   source test_src  { unix-stream("/tmp/syslog-ng-test");  };
   destination central_dest   { tcp("127.0.0.1" port(1999) ); };
   
   # Add this line to direct input from the test socket to stunnel
   log { source(test_src); destination(central_dest); };
   
   # Restart Syslog-ng to use the new configuration.  Make sure that both Stunnel and Syslog-ng are both running.  
   vdt-control --off syslog-ng
   vdt-control --on stunnel
   vdt-control --on syslog-ng
   
   # Then send a message to the UNIX socket
   logger -u /tmp/syslog-ng-test "Test message from host CLIENT-HOSTNAME"
   

Stunnel/Syslog-ng server setup

1. Get http public certificate from client. Add it to $VDT_LOCATION/stunnel/syslog-ng-client.pem. All client certificates must be added to this file.

   cat some-client-cert.pem >> $VDT_LOCATION/stunnel/syslog-ng-client.pem
   

2. Run configure_stunnel to setup Stunnel

   cd $VDT_LOCATION
   . setup.[c]sh
   # HOSTNAME = this server's hostname
   vdt/setup/configure_stunnel --setup-server --ca-file stunnel/syslog-ng-client.pem --host HOSTNAME --setup-syslog-ng
   # Enable Stunnel.  The --server flag tells Stunnel to be started with vdt-control.
   vdt/setup/configure_stunnel --server y
   
   # After this, to start services, use vdt-control
   vdt-control --on stunnel
   vdt-control --on syslog-ng
   

3. Adjust Syslog-ng's configuration appropriately. configure_stunnel will print the line that you need to add in order to read from stunnel:

   source secure_log {tcp(ip("127.0.0.1")  port(1999));};
   

   You will then need to redirect the stunnel input. For example:

   source secure_log {tcp(ip("127.0.0.1")  port(1999));};
   destination stunnel_dest { file("/tmp/syslog-stunnel.log"); };
   log { source(secure_log); destination(stunnel_dest); };