XINETD(1L)

NAME
xinetd - the extended Internet services daemon

SYNOPSIS
xinetd [options]

DESCRIPTION
xinetd performs the same function as inetd: it starts programs that provide Internet services. Instead of having such servers started at system initialization time, and be dormant until a connection request arrives, xinetd is the only daemon process started and it listens on all service ports for the services listed in its configuration file. When a request comes in, xinetd starts the appropriate server. Because of the way it operates, xinetd (as well as inetd) is also referred to as a super-server.

The services listed in xinetd's configuration file can be separated into two groups. Services in the first group are called multi-threaded and they require the forking of a new server process for each new connection request. The new server then handles that connection. For such services, xinetd keeps listening for new requests so that it can spawn new servers. On the other hand, the second group includes services for which the service daemon is responsible for handling all new connection requests. Such services are called single-threaded and xinetd will stop handling new requests for them until the server dies. Services in this group are usually datagram-based.

So far, the only reason for the existence of a super-server was to conserve system resources by avoiding to fork a lot of processes who might be dormant for most of their lifetime. While fulfilling this function, xinetd takes advantage of the idea of a super-server to provide features such as access control and logging. Furthermore, xinetd is not limited to services listed in /etc/services. Therefore, anybody can use of xinetd to start special-purpose servers.

OPTIONS

-d  Enables debug mode. This produces a lot of debugging output, and it makes it possible to use a debugger on xinetd.

-syslog syslog_facility
    This option enables syslog logging of xinetd-produced messages using the specified syslog facility. The following facility names are supported: daemon, auth, user, local[0-7] (check syslog.conf(5) for their meanings). This option is ineffective in debug mode since all relevant messages are sent to the terminal.

-filelog logfile
    xinetd-produced messages will be placed in the specified file. Messages are always appended to the file. If the file does not exist, it will be created. This option is ineffective in debug mode since all relevant messages are sent to the terminal.

-f config_file
    Determines the file that xinetd uses for configuration. The default is /etc/xinetd.conf.

-pid
    The process pid is written to standard error. This option is ineffective in debug mode.

-loop rate
    This option sets the loop rate beyond which a service is considered in error and is deactivated. The loop rate is specified in terms of the number of servers per second that can be forked for a process. The speed of your machine determines the correct value for this option. The default rate is 10.

-reuse
    If this option is used, xinetd will set the socket option SO_REUSEADDR before binding the service socket to an Internet address. This allows binding of the address even if there are programs that use it, which happens when a previous instance of xinetd has started some servers that are still running. This option has no effect on RPC services.

-limit proc_limit
    This option places a limit on the number of concurrently running processes that can be started by xinetd. Its purpose is to prevent process table overflows.

-logprocs limit
    This option places a limit on the number of concurrently running servers for remote userid acquisition.

-shutdownprocs limit
    This option places a limit on the number of concurrently running servers for service shutdown (forked when the RECORD option is used).

The syslog and filelog options are mutually exclusive. If none is specified, the default is syslog using the daemon facility. You should not confuse xinetd messages with messages related to service logging. The latter are logged only if this is specified via the configuration file.

CONFIGURATION FILE

The configuration file determines the services provided by xinetd. Any line whose first non-white-space character is a '#' is considered a comment line. Empty lines are ignored.

The file contains entries of the form:

    service <service_name>
    {
        <attribute> <assign_op> <value> <value> ...
        ...
    }

The assignment operator, assign_op, can be one of '=', '+=', '-='. The majority of attributes support only the simple assignment operator, '='. Attributes whose value is a set of values support all assignment operators. For such attributes, '+=' means adding a value to the set and '-=' means removing a value from the set. A list of these attributes will be given after all the attributes are described.

Each entry defines a service identified by the service_name. The following is a list of available attributes:

id  This attribute is used to uniquely identify a service. This is useful because there exist services that can use different protocols and need to be described with different entries in the configuration file. By default, the service id is the same as the service name.

type
    Possible values are:

    RPC if this is an RPC service

    INTERNAL
        if this is a service provided by xinetd.

    UNLISTED
        if this is a service not listed in /etc/services.

flags
    Possible flag values are:

    REUSE
        Set the SO_REUSEADDR flag on the service socket.

    INTERCEPT
        intercept packets or accepted connections in order to verify that they are coming from acceptable locations (internal or multi-threaded services cannot be intercepted).

    NORETRY
        avoid retry attempts in case of fork failure.

socket_type
    Possible values are:

    stream
        stream-based service

    dgram
        datagram-based service

    raw service that requires direct access to IP

    seqpacket
        service that requires reliable sequential datagram transmission

protocol
    determines the protocol that is employed by the service. The protocol must exist in /etc/protocols. If this attribute is not defined, the default protocol employed by the service will be used.

wait
    This attribute determines if the service is single-threaded or multi-threaded. If its value is yes the service is single-threaded; this means that xinetd will start the server and then it will stop handling requests for the service until the server dies. If the attribute value is no, the service is multi-threaded and xinetd will keep handling new service requests.

user
    determines the uid for the server process. The user name must exist in /etc/passwd. This attribute is ineffective if the effective user ID of xinetd is not super-user.

group
    determines the gid for the server process. The group name must exist in /etc/group. If a group is not specified, the group of user will be used (from /etc/passwd). This attribute is ineffective if the effective user ID of xinetd is not super-user.

instances
    determines the number of servers that can be simultaneously active for a service. By default, there is no limit. The value of this attribute can be either a number or UNLIMITED which means that there is no limit.

server
    determines the program to execute for this service.

server_args
    determines the arguments passed to the server. In contrast to inetd, the server name should not be included in server_args.

only_from
    determines the remote hosts to which the particular service is available. Its value is a list of IP addresses which can be specified in any combination of the following ways:

    a)  a numeric address in the form of %d.%d.%d.%d. If the rightmost components are 0, they are treated as wildcards (for example, 128.138.12.0 matches all hosts on the 128.138.12 subnet). 0.0.0.0 matches all Internet addresses.

    b)  a factorized address in the form of %d.%d.%d.{%d,%d,...}. There is no need for all 4 components (i.e. %d.%d.{%d,%d,...%d} is also ok). However, the factorized part must be at the end of the address.

    c)  a network name (from /etc/networks)

    d)  a host name. All IP addresses of the specified host name will be used.

    Specifying this attribute without a value makes the service available to nobody.

no_access
    determines the remote hosts to which the particular service is unavailable. Its value can be specified in the same way as the value of the only_from attribute. These two attributes determine the location access control enforced by xinetd. If none of the two is specified for a service, the service is available to anyone. If both are specified for a service, the one that is the better match for the address of the remote host determines if the service is available to that host (for example, if the only_from list contains 128.138.209.0 and the no_access list contains 128.138.209.10 then the host with the address 128.138.209.10 can not access the service).

access_times
    determines the time intervals when the service is available. An interval has the form hour:min-hour:min (connections will be accepted at the bounds of an interval). Hours can range from 0 to 23 and minutes from 0 to 59.

log_type
    determines where the service log output is sent. There are two formats:

    SYSLOG  syslog_facility [syslog_level]
        The log output is sent to syslog at the specified facility. If a level is present, the messages will be recorded at that level instead of LOG_INFO (which is the default level).

    FILE  file [soft_limit [hard_limit]]
        The log output is appended to file which will be created if it does not exist. Two limits on the size of the log file can be optionally specified. The first limit is a soft one; xinetd will log a message the first time this limit is exceeded (if xinetd logs to syslog, the message will be sent at the LOG_ALERT priority level). The second limit is a hard limit; xinetd will stop logging for the affected service (if the log file is a common log file, then more than one service may be affected) and will log a message about this (if xinetd logs to syslog, the message will be sent at the LOG_ALERT priority level). If a hard limit is not specified, it defaults to the soft limit increased by 1% but the extra size must be within the parameters LOG_EXTRA_MIN and LOG_EXTRA_MAX (defined in config.h).

log_on_success
    determines what information is logged when a server is started and when that server exits (the service id is always included in the log entry). Any combination of the following values may be specified:

    PID logs the server process id (if the service is implemented by xinetd without forking another process the logged process id will be 0)

    HOST
        logs the remote host address

    TIME
        logs the time when the server was started

    USERID
        logs the user id of the remote user using the RFC 931 identification protocol. This option is available only for multi-threaded stream services.

    EXIT
        logs the fact that a server exited along with the exit status or the termination signal (the process id is also logged if the PID option is used)

    DURATION
        logs the duration of a service session

log_on_failure
    determines what information is logged when a server cannot be started (either because of a lack of resources or because of access control restrictions). The service id is always included in the log entry along with the reason for failure. Any combination of the following values may be specified:

    HOST
        logs the remote host address

    TIME
        logs the time when the server was started

    USERID
        logs the user id of the remote user using the RFC 931 identification protocol. This option is available only for multi-threaded stream services.

    ATTEMPT
        logs the fact that a failed attempt was made

    RECORD
        records information from the remote end in case the server could not be started. This allows monitoring of attempts to use the service. For example, the login service logs the local user, remote user and terminal type. Currently, the services that support this option are: login, shell, exec, finger.

rpc_version
    determines the RPC version for a RPC service. The version can be a single number or a range in the form number-number.

env The value of this attribute is a list of strings of the form 'name=value'. These strings will be added to the environment before starting a server (therefore the server's environment will include xinetd's environment plus the specified strings).

passenv
    The value of this attribute is a list of environment variables from xinetd's environment that will be passed to the server.

port
    determines the service port. If this attribute is specified for a service listed in /etc/services, it must be equal to the port number listed in that file.

You don't need to specify all of the above attributes for each service. The necessary attributes for a service are:

    socket_type

    user
        (non-unlisted services only)

    server
        (non-internal services only)

    wait

    protocol
        (RPC and unlisted services only)

    rpc_version
        (RPC services only)

    port
        (unlisted services only)

The following attributes support all assignment operators:

    only_from

    no_access

    log_on_success

    log_on_failure

    passenv

    env (does not support the '-=' operator)

These attributes can also appear more than once in a service entry. The remaining attributes support only the '=' operator and can appear at most once in a service entry.

The configuration file may also contain a single defaults entry that has the form

    defaults
    {
        <attribute> = <value> <value> ...
        ...
    }

This entry provides default attribute values for service entries that don't specify those attributes. Possible default attributes:

    log_type

    log_on_success
        (cumulative effect)

    log_on_failure
        (cumulative effect)

    only_from
        (cumulative effect)

    no_access
        (cumulative effect)

    passenv
        (cumulative effect)

    instances

    disabled
        (cumulative effect)

Attributes with a cumulative effect can be specified multiple times with the values specified each time accumulating (i.e. '=' does the same thing as '+='). With the exception of disabled they all have the same meaning as if they were specified in a service entry. disabled determines services that are disabled even if they have entries in the configuration file. This allows for quick reconfiguration by specifying disabled services with the disabled attribute instead of commenting them out. The value of this attribute is a list of space separated service ids.

INTERNAL SERVICES

xinetd provides the following services internally (both stream and datagram based): echo, time, daytime, chargen, and discard. These services are under the same access restrictions as all other services except for the ones that don't require xinetd to fork another process for them. Those ones (time, daytime, and the datagram-based echo, chargen, and discard) have no limitation in the number of instances.

CONTROLLING XINETD

xinetd performs certain actions when it receives certain signals. The actions associated with the specific signals can be redefined by editing config.h and recompiling.

SIGUSR1
    causes a soft reconfiguration, which means that xinetd rereads the configuration file and adjusts accordingly.

SIGUSR2
    causes a hard reconfiguration, which is the same as a soft reconfiguration except that servers for services that are no longer available are terminated. Access control is performed again on running servers by checking the remote location, access times and server instances. If the number of server instances is lowered, some arbitrarily picked servers will be killed to satisfy the limit; this will happen after any servers are terminated because of failing the remote location or access time checks. Also, if the INTERCEPT flag was clear and is set, any running servers for that service will be terminated; the purpose of this is to ensure that after a hard reconfiguration there will be no running servers that can accept packets from addresses that do not meet the access control criteria.

SIGQUIT
    causes program termination.

SIGTERM
    terminates all running servers before terminating xinetd.

SIGHUP
    causes an internal state dump (the default dump file is /tmp/xinetd.dump; to change the filename, edit config.h and recompile).

SIGIOT
    causes an internal consistency check to verify that the data structures used by the program have not been corrupted. When the check is completed xinetd will generate a message that says if the check was successful or not.

On reconfiguration the log files are closed and reopened. This allows removal of old log files. Also, the following attributes cannot be changed on reconfiguration: socket_type, wait, protocol, type.

XINETD LOG FORMAT

Log entries are lines with the following format:
    entry: service-id data

The data depends on the entry. Possible entry types:

    START
        generated when a server is started

    EXIT
        generated when a server exits

    FAIL
        generated when it is not possible to start a server

    DATA
        generated when an attempt to start a server fails and the service supports the RECORD log option.

    USERID
        generated if the USERID log option is used.

In the following, the information enclosed in brackets appears if the appropriate log option is used.

A START entry has the format:
    START: service-id [pid=%d] [from=%d.%d.%d.%d] [time=time]
Time is given as year/month/day@hour:minutes:seconds.

An EXIT entry has the format:
    EXIT: service-id [type=%d] [pid=%d] [duration=%d(sec)]
type can be either status or signal. The number is either the exit status or the signal that caused process termination.

A FAIL entry has the format:
    FAIL: service-id reason [from=%d.%d.%d.%d] [time=time]
Possible reasons are:

    fork
        a certain number of consecutive fork attempts failed (this number is a configurable parameter)

    time
        the time check failed

    address
        the address check failed

    service_limit
        the allowed number of server instances for this service would be exceeded

    process_limit
        a limit on the number of forked processes was specified and it would be exceeded

A DATA entry has the format:
    DATA: service-id data
The data logged depends on the service.

    login
        remote_user=%s local_user=%s tty=%s

    exec
        remote_user=%s verify=status command=%s
        Possible status values:

        ok  the password was correct

        failed
            the password was incorrect

        baduser
            no such user

    shell
        remote_user=%s local_user=%s command=%s

    finger
        received string or EMPTY-LINE

A USERID entry has the format:
    USERID: text
The text is the response of the RFC 931 daemon at the remote end excluding the port numbers (which are included in the response).

EXAMPLE

    #
    # Sample configuration file for xinetd
    #
    defaults
    {

        log_type
            = FILE /var/log/servicelog

        log_on_success
            = PID

        log_on_failure
            = HOST TIME RECORD

        only_from
            = 128.138.193.0 128.138.204.0 128.138.209.0

        only_from
            = 128.138.252.1

        instances
            = 10

        disabled
            = rstatd
    }
    #
    # Note 1: the protocol attribute is not required
    # Note 2: the instances attribute overrides the default
    #
    service login
    {

        socket_type
            = stream

        protocol
            = tcp

        wait
            = no

        user
            = root

        server
            = /usr/etc/in.rlogind

        instances
            = UNLIMITED
    }
    #
    # Note 1: the instances attribute overrides the default
    # Note 2: the log_on_success flags are augmented
    #
    service shell
    {

        socket_type
            = stream

        wait
            = no

        user
            = root

        instances
            = UNLIMITED

        server
            = /usr/etc/in.rshd

        log_on_success
            += HOST TIME RECORD
    }
    service ftp
    {

        socket_type
            = stream

        wait
            = no

        user
            = root

        server
            = /usr/etc/in.ftpd

        server_args
            = -l

        instances
            = 4

        log_on_success
            += DURATION HOST USERID

        access_times
            = 2:00-9:00 12:00-24:00
    }
    #
    # This entry and the next one specify internal services. Since this
    # is the same service using a different socket type, the id attribute
    # is used to uniquely identify each entry
    #
    service echo
    {

        id  = echo-stream

        type
            = INTERNAL

        socket_type
            = stream

        user
            = root

        wait
            = no
    }
    service echo
    {

        id  = echo-dgram

        type
            = INTERNAL

        socket_type
            = dgram

        user
            = root

        wait
            = no
    }
    #
    # Sample RPC service
    #
    service rstatd
    {

        type
            = RPC

        socket_type
            = dgram

        protocol
            = udp

        server
            = /usr/etc/rpc.rstatd

        wait
            = yes

        user
            = root

        rpc_version
            = 2-4

        env = LD_LIBRARY_PATH=/etc/securelib
    }
    #
    # Sample unlisted service
    #
    service unlisted
    {

        type
            = UNLISTED

        socket_type
            = stream

        protocol
            = tcp

        wait
            = no

        server
            = /home/user/some_server

        port
            = 20020
    }

FILES

/etc/xinetd.conf
    default configuration file

/tmp/xinetd.dump
    default dump file

SEE ALSO
inetd(8),

Postel J., Echo Protocol , RFC 862, May 1983

Postel J., Discard Protocol , RFC 863, May 1983

Postel J., Character Generator Protocol , RFC 864, May 1983

Postel J., Daytime Protocol , RFC 867, May 1983

Postel J., Harrenstien K., Time Protocol , RFC 868, May 1983

StJohns M., Authentication Server , RFC 931, January 1985

AUTHOR
Panos Tsirigotis, CS Dept, University of Colorado, Boulder

NOTES
When the attributes only_from and no_access are not specified for a service (either directly or via defaults) the address check is considered successful (i.e. access will not be denied).

If the USERID log option is specified and the remote RFC 931 server sends back an ERROR reply, access will not be denied.

If the USERID log option is specified and the remote host does not run a RFC 931 server, there will be no indication in the log of that fact (other than the missing USERID log entry).

BUGS

Supplementary group ids are not supported.

If the INTERCEPT flag is not used, access control on the address of the remote host is not performed when wait is yes and socket_type is stream.

If the INTERCEPT flag is not used, access control on the address of the remote host for services where wait is yes and socket_type is dgram is performed only on the first packet. The server may then accept packets from hosts not in the access control list. This can happen with RPC services.

Unlisted RPC services are not supported, i.e. all RPC services must be registered in /etc/rpc. Specifying an RPC service by its RPC program number is not (yet) possible.

There is no way to put a SPACE in an environment variable.

When wait is yes and socket_type is stream, the socket passed to the server can only accept connections.

The INTERCEPT flag is not supported for internal services or multi-threaded services.

Interception works by forking a process which acts as a filter between the remote host(s) and the local server. This obviously has a performance impact which depends on the volume of information exchanged. It is up to you to make the compromise between security and performance for each service.

PRONUNCIATION
zy-net-d