3.5 Server Configuration

Servers are internal smapd objects, responsible for listening on sockets and handling socket I/O operations. Each server has a server id, which is a unique name associated with it, and socket address, which describes the socket this server handles.

Socket addresses are represented as URLs. Smap version 2.1 recognizes the following URL forms:

inet://ip:port

Listen on the IPv4 address ip, on the given port. IP address may be given either in “dotted-quad” notation or as a hostname. Port may be specified either as a port number, or as a name of a service from /etc/services.

unix://pathname

Listen on the UNIX socket pathname. Notice that the name of the socket must be absolute, so you would usually have three slashes running together, e.g. the notation

unix:///var/run/smap.sock

means UNIX socket /var/run/smap.sock.

The server statement configures servers. It takes two mandatory arguments: the socked ID and URL, e.g.:

server main inet://10.10.1.11:3056
server local unix:///var/run/smap.sock

These statements configure two servers. The one called ‘main’ is listening on IP 10.10.1.11, port 3056. The one called ‘local’ listens on UNIX socket /var/run/smap.sock.

If a server is assigned an ‘inet’ address, access to it will be controlled by TCP wrappers. The server ID is used as daemon name. See the next section (see TCP wrappers) for a detailed description.

The server statement has also another form, called block form, which allows to configure more details. In this form, the statement is given third argument – the word ‘begin’. This statement is followed by one or more statements supplying additional configuration for this server, followed by the word ‘end’ on a line by itself, which closes the construct. This is illustrated in the following example:

server local unix:///var/run/smap.sock begin
  backlog 10
  user mail
end  

Statements which may be used between ‘begin’ and ‘end’ fall into two categories: privilege control statements, and socket configuration statements.

The former are user, allgroups and group, described in the previous section (see privileges). Syntactically they are exactly the same as their public scope counterparts. The only difference is that they apply only to child processes spawned to handle connections to that particular URL. For example, consider the following statement:

server local unix:///var/run/smap.sock begin
  user daemon
  group mail mysql
end  

This configuration works as follows. The master smapd process runs with root privileges. When a connection is requested to socket /var/run/smap.sock, the master spawns a subprocess to handle that connection. This subprocess switches to the UID and GID of user ‘daemon’ and retains GIDs of the groups ‘mail’ and ‘mysql’ and then enters the mail read-and-reply loop. The ownership of the socket /var/run/smap.sock is set to UID of user ‘daemon’ and GID of its primary group (see also the description of owner, below).

Of course, the per-server privilege control statements work only if the master daemon runs with the root privileges.

The second group of server statements are socket configuration statements. Similarly to privilege control statements, these too may appear inside a server block statement as well as outside of it, in the global scope (with the exception of the owner statement, which is allowed only in server scope). When used in global scope, they affect all server statements. When used in per-server context, they apply to that particular server only. These statements are:

Config: backlog number

Sets the maximum size of pending connections queue for sockets. If a connection request arrives when the queue is full, the client receives an error with an indication of ‘ECONNREFUSED’.

Default backlog is 8.

Config: reuseaddr bool

If bool is ‘yes’ reuse existing socket addresses (both INET and UNIX). This is the default.

Config: max-children number

Maximum number of children processes allowed to run simultaneously. When the actual number of children reaches number, the server stops refusing further connections until any of them terminates. The value of ‘0’ means ‘unlimited’.

The default limit is ‘128’.

Config: single-process bool

Operate in single-process mode. This options may become necessary only when debugging the smapd daemon. Never use it in production environment!

Config: socket-mode mode

Set file mode for UNIX socket. Specify the mode argument either int octal notation (e.g. ‘600’), or in chmod-style notation (e.g. ‘rw-------’).

Config: socket-owner user:group

Set socket ownership to the given user and group. This applies only to UNIX sockets. User and group may be specified either by their symbolic names or numeric IDs. Either user or group may be omitted. There are following cases:

owner user:group

Set both owner UID and GID.

owner user

Set UID of the user user and GID of his primary group.

owner user:

Set UID of the user user, but do not change the GID.

owner :group

Set only owner GID, do not change the UID.

Note, that this statement cannot be used outside of server scope.