/* Copyright (C) 1996-2008 Mike Harrelson The Console Logger is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. The Console Logger is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. The GNU General Public License is often shipped with GNU software, and is generally kept in a file called COPYING or LICENSE. If you do not have a copy of the license, write to the Free Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. */ Console Logger v1.15.x Documentation Introduction Many UNIX shops have accessed the consoles of their UNIX boxes by connecting to their serial ports via some kind of terminal server. Typically pormasters or cyclades were used as terminal servers to manage the large number of serial ports. The problem with Portmasters was that there was limited access and no logging of output. Cyclades improve on this somewhat adding some new capabilities not previously available. Console Logger was written to solve these problems. It runs from an admin host that has access to all of the terminal servers. A shop configures its terminal servers (Portmaster, Cyclades, etc.) to map a TCP port to an individual serial port (each connected to one machine). The telnet protocol is used over this interface. Access should be restricted by the network security model, and all traffic should operate over a switched network, so sniffing is difficult. All other access from the outside to the internal network should be over an encryption network (typically SSH). Console Logger's main features are 1) ease of access, 2) raw console output to logfiles, 3) Combined and timestamped log output for monitoring, 4) attachment to and management of consoles by personel, and 5) abillity to watch console activity without attaching. Console Logger was designed to not be dependant on any other services such as DNS, LDAP, or Kerberos which may not be available in a crisis. It was also designed to operate with as few system resources as possible (memory, CPU, etc). It uses a central configuration file for most of its parameters. It can also receive signals to carry out special operations such as re-reading its configuration file or open/closing logfiles. Since its code is open source, admins have full control over its capabilities. Configuration Console Logger uses a central configuration file. A parameter is passed to Console Logger specifying the full path of the configuration file. There are three groups of definitions in the configuration file that the administrator should be concerned about. They can appear almost anywhere in the file as long as the format coorect. Lines beginning with '#' or are empty are ignored. The first group of definitions are the global options. Currently seven global options are used: LOG=consoled.log ROOT R.8eHa2/IxqpG USER joesmoe 522e18d3ce0bdd8d5f098c626ece USER sallymae USER billybob Ha2/IxR.8Ge LOGDIR=/var/log/consoles LISTEN 6000 PIDFILE /var/tmp/consoled.pid CLOG Combined.log RUNAS nobody POOLSIZE 500 SYSLOG LOG_SYSLOG LOG_DEBUG BIND 127.0.0.1 Each item above is denoted at the beginning of the line by a keyword followed by a value. The two can be seperated by an '=' sign or whitespace (both are demonstrated above). Either/or works fine. The keywords are NOT case senstive. All of the above are required except for the 'ROOT' line which can be left out if no global password is wanted. The 'LOG' keyword denotes the logfile for Console Logger itself. This log file holds error condition or events that Console Logger encounters. Things such as user logins, console attachments, user logouts, unexpected console disconnects, etc. are logged along with a timestamp and whoever (if applicable) initiated the action. Received signals are also logged as well as the resulting action. The 'ROOT' keyword specifies a DES hash (or special hash) for the Console Logger global password. The functionality is fully implemented as of v1.4. Previously Console Logger enforced no notion of true users, but used the GID of the given user to determine access. This keyword pair can be commented out or omitted from the configuration file if no global password is wanted. If it is not specified, Console Logger will not prompt for a password (see exception below). The login in these cases is purely for bookeeping purposes. Related to the 'ROOT' keyword is the 'USER' keyword. It allows an individual user to set a password for only that username. The 'USER' directive overrides 'ROOT' (unless the password hash is left off) and is enforced whether 'ROOT' is set or not. Any number of users can be specified. The special hash value can be generated using the 'makehash' utility or a DES hash can be used. This function was added in 1.5. If the password hash is left off, no password will be prompted for unless the global password is set via the 'ROOT' option. The 'USER" option can also be used to identify users who may not be in the /etc/passwd file or in the proper Unix group. The 'LOGDIR' keyword specifies the logging directory in which the various various logfiles will be kept (if no abosolute path is given). Console Logger also chdir's into this directory when it starts up. The user that Console Logger runs as needs to have read+write permission to this directory. 'LISTEN' specifies which local TCP port Console Logger will listen on to accept new connections. At one employer of mine, the port was 6000 which is the range currently set for the Portmasters (the Cyclades were configured for port 7000 ranges). If Console Logger is not running as root (which it generally does not need to do) then the port needs to be set above 1024. The 'PIDFILE' specifies the file (including path) to use as a PID file. This file is mainly used by the startup/shutdown init.d scripts to send signals to Console Logger. Administrators can also send signals to Console Logger using the PID file. The init.d script currently expects the PID file to be '/var/tmp/consoled.pid'. The 'CLOG' keyword specifies the filename of the "combined" logfile. All output to raw logs for consoles that are not attached to is captured, line-buffered, stripped of 8-bit and nonprintable characters, timestamped and machine stamped, and then stored in this file. This allows one to view all free console output in one location for monitoring. Each of these keywords should appear only once, but additional instances replace the previous value. The 'RUNAS' option specifies what user Console Logger should run as after startup initialization. Console Logger must be started as root in order for this to work as only root can setuid() to another user. For security reason, consoled should not run as root (after startup). However, the log directories must be writable by the specified user so that log files can be created and updated. The 'POOLSIZE' option specifies the maximum number of consoles to support. This option is used to raise the resource limits for file and socket descriptors. The formula is as follows rlimit = poolsize * 2 + 24. The 24 is for global log files, remote logins, and place holders. Roughly 20 remote logins are allowed. If the reources for maxfiles needs to be raised, upping POOLSIZE will do so. Since only root is allowed to raise past the hard limit, this option only has effect on startup (assuming it is started as root). Next, the 'SYSLOG' option allow you to send Console Logger's log output as well as the combined log to the specified syslog facility. See the man page for syslog(3C) to get the options for the facility and level. If the SYSLOG option is omitted or commented out, then nothing is logged to the syslog facility. The first option specifies the facility and the last specifies the level (or priority). Finally, the BIND option allows you to tell Console Logger to only listen for incoming connections on a particular interface. A local IP address should be sepcified if it is to accept incoming connections only from that interface. '*' can be used to spedify any/all addresses. IF the option is missing or commented out, Console Logger binds to all interfaces. The second group in the configuration file is the network allowance section. The definitions in this section resemble and act like TCPwrappers. It consists of an 'ALLOW' keyword (also not case senstive) and an opening brace '{'. On each line afterwards there should be an IP address or subaddress. An example is given below: ALLOW { # one entry per line follows 127.0.0.1 #obviously need this 172.134.200.254 #allow this host to connect 10.30.112 #an internal NAT'd network - entire range allowed } The section is terminated with a closed brace '}' on a line by itself. This section should appear only once in the config file. The listed networks or IP addresses specified are ALLOWED to connect to Console Logger. All others will be rejected with the attempt being logged to Console Logger's logfile. Successful logins are logged as well. The last group of definitions can have multiple sections. Each instance defines a specific terminal server (colorfully called a doormat in Console Logger) and the consoles connected to it. The 'CONSOLES' keyword denotes the beginning of a new terminal server section. It is followed (on the same line) by a terminal server name, then an IP address for that terminal server. Finally, an opening brace '{' ends the line. The lines following (one per line) specify the individual console information. The format is '