Starting and stopping syslogd

You must start the syslog daemon (syslogd) from a user ID with superuser authority (UID 0). You can start syslogd from the z/OS® UNIX System Services shell, from a started procedure using BPXBATCH, or from a started procedure that directly invokes syslogd. To ensure that syslogd services are available to applications during TCP/IP initialization, start syslogd from the z/OS UNIX System Services initialization shell script /etc/rc.

#
# Start the syslogd daemon 
#    Export any syslogd environment variables before starting syslogd.
#
#    The ampersand (&) symbol is necessary to allow the z/OS Unix System 
#    Services initialization to continue while syslogd starts. 
#
#    
#
export _BPX_JOBNAME='SYSLOGD1'
/usr/sbin/syslogd -f /etc/syslogd.conf &

If there is no TCP/IP transport active when syslogd starts or when TCP/IP is recycled, syslogd remains active until it can establish or reestablish communication with TCP/IP.

Rules:

If you start syslogd from a shell script, start it as a background shell command by specifying an ampersand (&) as the last character on the command. If you do not specify the ampersand, control does not return to the shell until syslogd ends. When starting syslogd from the /etc/rc script it is especially important to code the ampersand; if you do not code the ampersand, z/OS UNIX System Services initialization cannot complete.
If you start syslogd from a shell script and you call the shell script from a started procedure using BPXBATCH, you need to add a sleep shell command to your script after the start of syslogd. The sleep command prevents the shell script from ending before syslogd initialization completes.
If you start syslogd from a shell script and you call the shell script from a started procedure using BPXBATCH, you must use a z/OS UNIX file for the STDOUT and STDERR DD statements; otherwise the started procedure cannot end.

Guidelines:

When starting syslogd from a shell script, the resulting job name is the user ID under which the shell script is running. You can override the default job name by setting and exporting the _BPX_JOBNAME environment variable in your shell script.
When starting syslogd from a started procedure, the resulting job name is the same as the name of the started procedure. You can override the default job name by setting the JOBNAME= parameter. For example:
```
S SYSLOGD1,JOBNAME=SYSLOGD
```
When starting syslogd from a shell script, export the environment variables before starting syslogd. The following example defines the syslogd configuration file:
```
#
# Shell script to start syslogd
#
export _BPX_JOBNAME='SYSLOGD1'
export SYSLOGD_CONFIG_FILE="//'HLQ.SYSLOGD.CONFIG(DEFAULT)'"
 /usr/sbin/syslogd &
```
When starting syslogd directly from a started procedure, place the syslogd environment variables in a z/OS UNIX file or MVS™ data set. Use the following technique to pass the environment variables to syslogd.
```
// PARM='ENVAR("_CEE_ENVFILE=DD:STDENV")/'

//STDENV DD PATH='/etc/syslogd.env',PATHOPTS=(ORDONLY)
or
//STDENV DD DSN=HLQ.SYSLOGD.ENV(DEFAULT),DISP=SHR
```
When you use an MVS data set for your syslogd environment variables, place the environment variables in a data set with the VB record format [RECFM(VB)] and a logical record length of 256 [LRECL(256)]. If you use any other record format for the data set, use the _CEE_ENVFILE_S environment variable in place of the _CEE_ENVFILE environment variable in your syslogd started procedure. When the _CEE_ENVFILE_S environment variable is used, the system removes trailing blank spaces from each NAME=VALUE line that is read. For additional information about the _CEE_ENVFILE_S environment variable, see z/OS XL C/C++ Programming Guide.

Syslogd can run in one of three modes:

Normal
In this mode, syslogd processes logging requests from the local system and applications using the syslog() function. Additionally, syslogd receives and logs messages sent over the IP network by remote systems running syslogd. These remote systems can be z/OS systems or non-z/OS systems. Only one instance of syslogd can be run on a z/OS system if syslogd is started in this mode.
Local-only
In this mode, syslogd processes logging requests from only the local system and applications. This instance of syslogd does not receive or process messages sent over the network from remote syslog daemons. Use the -i option to start syslogd in the local-only mode.
Network-only
In this mode, syslogd processes only messages sent over the network by remote systems running syslogd. This instance of syslogd does not process logging requests from the local system or applications. Use the -n option to start syslogd in the network-only mode.

In all three modes, syslogd can send messages to remote syslog daemons.

Requirement: You must install and activate the AF_UNIX domain prior to starting syslogd in normal or local-only mode.

As shown in Table 1, how you choose to run syslogd depends on your logging requirements.

Table 1. Mode to use for different logging requirements
Logging requirement	How to run syslogd
You have a low volume of messages that you want to process from the network.	Run a single instance of syslogd in normal mode.
You do not want to process any log messages from remote syslog daemons over the network.	Run a single instance of syslogd in local-only mode.
You have a high volume of log messages from remote syslogd daemons that you want to log with syslogd.	Run two instances of syslogd. Start syslogd in local-only mode to process all local messages. Start another instance of syslogd in network-only mode to process the remote syslog messages. Two instances of syslogd provide better performance than running a single instance of syslogd in normal mode, especially in high-volume situations.

Restriction: A maximum of two instances of syslogd can be started. If you are going to start more than one instance of syslogd on the same z/OS image, one instance must be started in local-only mode and one instance must be started in network-only mode. Never run just one instance of syslogd in network-only mode. If an instance of syslogd is not processing local system and application messages, these messages are written to the MVS console and might result in message flooding on the MVS console.

To record timestamps more accurately, you need to set the TZ environment variable to local time. You can set the TZ environment variable in the following ways:

When you start syslogd from the z/OS shell
Export the TZ environment variable before you start syslogd. Export it in /etc/profile or in .profile in the HOME directory. For example, if you are in the Eastern time zone in the United States, issue the following command:
```
export TZ=EST5EDT
```
When you are starting syslogd as a started task, use either of the following methods:
- Specify TZ using the ENVAR parameter on the PARM statement in the started procedure. For example:
```
// PARM='ENVAR("TZ=EST5EDT")/'
```
- Export the TZ environment variable in a file specified with the STDENV DD statement. For example:
```
// PARM='ENVAR("_CEE_ENVFILE=DD:STDENV")/'
//STDENV DD PATH='/etc/syslogd.env',PATHOPTS=(ORDONLY)
```
  Place the following statement in the /etc/syslogd.env file:
```
TZ=EST5EDT
```
  Use the STDENV DD statement when you want to specify more than one environment variable; there is a JCL limit of 100 characters on the PARM parameter. Language Environment® recommends a variable record format for the STDENV file.

You can also set the TZ environment variable for all applications in the CEEPRMxx PARMLIB member. You should define the TZ environment variable for all three LE option sets (CEEDOPT, CEECOPT, and CELQDOPT). For example:

CEECOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )
CEEDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )
CELQDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )

For more information about specifying run-time options, see z/OS Language Environment Programming Guide. For details on setting the TZ environment variable, see z/OS UNIX System Services Command Reference.

The following syntax is the syntax for the syslogd command:

syslogd [-c] [-d] [-D value] [-f conffile] [-F value] [-i] [-m markinterval] [-n] [-p logpath] [-u] [-x] [-?] &

The syslogd command recognizes the following options:

-c

Create log files and directories automatically. The -c option is required to use the automatic archive function (see Configuring syslogd for automatic archiving).

-d

Run syslogd in debugging mode (see Diagnosing syslogd configuration problems for more information).

-D

Default access permissions (modes) to be used by syslogd when creating directories. This parameter is valid only when specified in conjunction with the -c option. The parameter value is specified as an octal number 1- 4 characters in length. Leading zeros can be omitted. The following values can be ORed together to form the parameter value:

Value: Description
2000: Set GID
1000: Sticky bit (deletion restricted to owner or superuser)
0400: User read
0200: User write
0100: User list directory
0040: Group read
0020: Group write
0010: Group list directory
0004: Other read
0002: Other write
0001: Other list directory

If the -D option is not specified, the default value 0700 is used. Value 0000 and bits other than the ones shown are not valid. For example, you cannot set the set-UID bit for a directory. z/OS does not use the set-GID bit during directory creation regardless of whether the bit was set in the directory permissions.

-f

Configuration file name. You can also specify the configuration file using the SYSLOGD_CONFIG_FILE environment variable. The -f option overrides the environment variable.

-F

Default access permissions (modes) to be used by syslogd when creating log files. This parameter is valid only when specified in conjunction with the -c option. The parameter value is specified as an octal number 1 - 4 characters in length. Leading zeros can be omitted. The following values can be ORed together to form the parameter value:

Value: Description
0400: User read
0200: User write
0040: Group read
0020: Group write
0004: Other read
0002: Other write

If the -F option is not specified, the default value 600 is used. The actual permissions are modified by the syslogd process umask value at the time when the file is created. This parameter is used only when syslogd must create a log file dynamically; it has no effect on log files that already exist. Value 0000 and bits other than the ones shown are not valid. For example, you cannot set the execute bits, set-UID, set-GID, or the sticky bit for log files.

-i

Start in local-only mode, and do not receive messages from the IP network. This option is mutually exclusive with the -n option. If syslogd is started with the -i option, another instance of syslogd can be started with the -n option. This is the only supported way to run two instances of syslogd on the same z/OS image. Syslogd can still send messages to remote syslogd instances when it is running in local-only mode.

-m

Number of minutes between mark messages. The default value is 20 minutes. The following rule must be coded for each logfile that you want a mark record recorded in: mark.info.

-n

Start in network-only mode, and receive messages from only the IP network. This option is mutually exclusive with the -i option. If syslogd is started with the -n option, another instance of syslogd can be started with the -i option. This is the only supported way to run two instances of syslogd on the same z/OS image. Syslogd can still send messages to remote syslogd instances when it is running in network-only mode.

-p

Path name of the z/OS UNIX character device for the datagram socket. The default value is /dev/log. You can also specify the path name using the SYSLOGD_PATH_NAME environment variable. The -p option overrides the environment variable.

Note: This option is not used frequently. If you selected the -p option, syslogd will not function properly.

-u

For records received over the AF_UNIX socket (most messages generated on the local system), include the user ID and job name in the record. In this case, a forward slash, the user ID, and the job name will follow the local host name for messages received over the AF_UNIX socket. The forward slash, which immediately follows the local host name, can be used to determine whether or not the user ID and job name is being recorded. If not recorded, a blank immediately follows the local host name. When user ID or job name is not available, N/A will be written in the corresponding field.

-x

Disable host name resolution for messages received from the IP network. This option is mutually exclusive with the -i option. Using this option can improve the performance of syslogd when processing messages received from the IP network. It has no effect for local messages. When you use this option, the IP address (instead of the host name) of the origin host is logged, along with the message text. If the host name can be determined from the rule without having to make a resolver call, the host name is used instead of the IP address. When the -x option is not used, syslogd always attempts to resolve the host name associated with a log message arriving from the IP network. If the host name cannot be determined, the IP address is logged as the message origin instead of the host name.

-?

Show syslogd command-line options.

To specify the job name and pass the appropriate environment variables to the syslogd process, start syslogd by using a shell script such as the following script:

#
# Start the syslog daemon
#
 
export _BPX_JOBNAME='syslogd'
/usr/sbin/syslogd -f /etc/syslog.conf &

You can execute this shell script directly from the /etc/rc file to start syslogd at z/OS UNIX initialization.

If an incorrect argument or number of arguments is entered, syslogd exits and the return code is 1. In all other situations in which syslogd exits, the return code is 0.

To terminate syslogd, you can issue the STOP command, issue the MODIFY command, or send a SIGTERM signal.

STOP jobname

MODIFY BPXOINIT,TERM=processID

kill -s TERM processID

To force syslogd to reread its configuration file and activate any modified parameters without stopping, issue the MODIFY procname,RESTART command or send a SIGHUP signal. This also causes any host names specified in rule selectors or destinations to be resolved again to IP addresses. After rereading the configuration file, syslogd continues to append log messages to the files that you specify in /etc/syslog.conf.

MODIFY procname,RESTART

kill -s HUP processID

The syslog daemon stores its process ID in the /etc/syslog.pid file or the /etc/syslog_net.pid file, so that it can be used to terminate or reconfigure the daemon. If syslogd is started in normal or local-only mode, the /etc/syslog.pid file is used to store the process ID. If syslogd is started in the network-only mode, the /etc/syslog_net.pid file is used to store the process ID.

Restrictions: Start of change

If /etc/syslog.pid or /etc/syslog net.pid is a symbolic link, it must have an owning UID or GID that matches the EUID or EGID that is assigned to the syslog daemon.
If /etc/syslog.pid or /etc/syslog_net.pid is a hard link or the target of a hard link, users that are outside the owner or group of the directory in which /etc/syslog.pid or /etc/syslog_net.pid is stored cannot have write access to the directory. Additionally, write access to /etc/syslog.pid and /etc/syslog_net.pid must be limited to the owning UID or group, for example, --w--w----permissions.

Rule: If the BPX.SMF FACILITY class resource is defined and SMF records are to be written by syslogd, the user ID with which syslogd runs must also be permitted to SAF resource BPX.SMF. See SEZAINST(EZARACF) for more information.

Tips:

Messages are read from the UNIX domain datagram socket (unless the -n option is specified), and from the IPv4 (AF_INET) or IPv6 (AF_INET6) Internet domain datagram socket (unless the -i option is specified).
Messages written to a local instance of syslogd with the kern facility are converted to the user facility. If syslogd receives a log message over the network with the kern facility, the facility is not changed.

For more information about the facilities used by z/OS Communications Server functions, see Table 1.