11. Sending commands to clients

It is generally not possible to send commands to clients, because the client does not listen on the network (the client needs root privileges to perform its tasks, and you don't want a root network daemon).

However, it is possible to send a command if and when a client connects to deliver a message. As of version 1.8.0, clients use a new version of the client/server protocol, which includes a set of pre-defined commands that are understood by the client. Currently implemented are RELOAD to reload the configuration, SCAN to request a file system check (ouside the regular schedule), and STOP to terminate the client.

Pre-1.8.0 clients, or clients build with the (optional) old protocol version, will simply ignore such commands.

11.1. Communicating with the server

As of version 1.8.0, yule can send a command to a client if and when a client connects to deliver a message, e.g. a timestamp message (clients are not listening on the network, and thus commands can only be sent together with the confirmation when a message is received).

Of course the server needs to know which (if any) command to send. Therefore it can open a unix domain socket upon startup (in the same directory as the PID file). Opening this command interface must be requested explicitely with the option SetUseSocket= yes (in the [Misc] section).

A separate application yulectl is compiled together with the server that provides a command-line interface to access this facility. Use yulectl -h for help.

11.2. Authenticating to the server

There are two methods to authenticate to the server. If supported by the OS, authentication is done by passing the credentials of the socket peer to the server (this is a special feature of unix domain sockets), and requiring the UID of the the socket peer (i.e. the user using the yulectl program) to match a UID as set with the SetSocketAllowUid= UID option (default is 0, i.e. only root can use the interface).

[Note]Note

If passing credentials over the socket is supported by the OS, it is not possible to fake these credentials - they are supplied by the kernel. Therefore, the server can rely on the fact that the user process writing to the socket has indeed the UID passed via the socket. Thus, the access rights to the socket are basically not important (on some systems, they are not even recognized/respected at all).

As of version 1.8.12, if (and only if) passing credentials over the socket is not supported, you can specify a password with the SetSocketPassword= password option. The password must be 14 characters or less, and must not include the '@' character.

Of course you must supply the password to yulectl if you want to communicate with the server. To do so, create a file .yulectl_cred in your home directory, and place the password there.

[Note]Note

Password authentication is not supported if the OS supports the aforementioned method. You can use yule -v to find out which of the two authentication methods is supported.