dc_client (1) - Linux Manuals

dc_client: Distributed session cache client proxy

NAME

dc_client - Distributed session cache client proxy

SYNOPSIS

dc_client -server <address> [options]

DESCRIPTION

dc_client runs a client proxy to provide access to a remote cache server (typically over TCP/IPv4) by providing a local service (typically over unix domain sockets). It starts listening on a configurable network address for connections and establishes a persistent connection to an instance of dc_server for proxying cache operations to. Incoming connections are expected to communicate using the distcache(8) protocol, and would typically be applications using one of the distcache APIs in libdistcache to encapsulate these communications.

The common use of dc_client is to run as a local agent on each host machine that requires use of the distributed cache, as the listening address should probably use unix domain sockets which are better suited to frequent (and temporary) connections being used for individual cache operations. Likewise, the connection dc_client makes to the cache server (dc_server) for proxying cache operations is typically over a genuine network to remote machine, using TCP/IPv4.

OPTIONS

-daemon

After initialising, dc_client will detach from the parent process, close standard file-descriptors, etc. If this flag is not set, dc_client will run in the foreground. It is recommended to use this flag in combination with the pidfile flag to simplify stopping and restarting services.

-user user

This switch will attempt to change user privileges of dc_client to the given user ID after initialising its listening socket. On most systems, this can only work if dc_client is started as the root user. It is important to note that the change of user ID occurs after the listening socket is created but before any attempts are made to connect to distcache servers. This ensures that the listening socket is created with the most restrictive permissions, and that the ability to connect to servers at run-time corresponds to the given user (rather than having unusual root permissions on startup).

-listen address

Configures the address on which dc_client should listen for incoming connections. The syntax is that defined by the libnal API. Though this can listen on any supported network transport, dc_client should be expected to receive a lot of short-lived (and frequest) connections, so unix domain sockets are generally preferable to TCP/IPv4. Eg.

    # Listen on a unix domain socket in the /tmp directory
    dc_client -listen UNIX:/tmp/cacheclient

The default value for this flag is: UNIX:/tmp/scache

-sockowner user

This switch is only useful when listening (see -listen) on unix domain sockets. It will attempt to change ownership of the created socket file.

-sockgroup group

This switch is only useful when listening (see -listen) on unix domain sockets. It will attempt to change group ownership of the created socket file.

-sockperms perms

This switch is only useful when listening (see -listen) on unix domain sockets. It will attempt to change file permissions for the created socket file, and is specified in the standard octal notation used for unix file permissions. Eg. to start dc_client to run as the nobody user, listening on a unix domain socket that can only be connected to by the root user or members of the ssl group;

    # dc_client -listen UNIX:/tmp/cacheclient -user nobody \
          -sockgroup ssl -sockperms 440

-server address

-connect address

These flags are identical, and specify the address of the cache server dc_client should connect to. Cache operations requested by clients of dc_client (using short-lived local connections to the service address specified by -listen) are multiplexed to/from the cache server over this persistent connection. The syntax is that defined by the libnal API and would typically be over TCP/IPv4, particularly if the cache server is running on a remote machine. Eg.

    # Connect to a remote cache server listening on port 9001
    dc_client -listen UNIX:/tmp/cacheclient \
              -server IP:cacheserver.localnet:9001

-retry msecs

Distcache is designed to be as fault-tolerant as possible, and part of this approach is to have dc_client manage the possible disappearance and subsequent reappearance of the remote instance of dc_server it proxies to. In actuality, this could happen for a variety of reasons including the cache server being restarted, or a network error at any point in between the two programs. During any period in which dc_client has lost communications with the cache server, any/all local connections and corresponding cache operation requests will be responded to directly by dc_client itself. The consequence is that cache operations return as failures during this time, so the application requesting the operations must make do without (eg. in SSL/TLS session caching, this means that attempts to resume SSL/TLS sessions fail and so full handshakes are required).

The default behaviour of dc_client when losing communications with the instance of dc_server (as specified by -server or -connect) is to try to reestablish communications every 5 seconds. This flag allows the retry period to be configured to any number of milliseconds. Note: confusing milliseconds with seconds can cause emotional disturbance and should be avoided at all costs.

-idle msecs

Normal behaviour with dc_client is to have its clients (applications using distcache(8) APIs for communication) use temporary connections for each cache operation. However, there are modes of operation in those APIs that allow persistent connections to be used together with various associated options. This is especially important for any platforms that (for whatever reason) can't use unix domain sockets and don't want to bloat file-descriptor tables with IPv4 sockets sitting in TIME_WAIT state. For this reason, as well as resilience against client applications that hang, it useful to configure dc_client to automatically drop client connections that have been idle for some configurable period of time.

This flag specifies the period of idle time after which client connections will be dropped, and is in units of milliseconds and not seconds. The default value is zero, and this means that client connections are never intentionally dropped.

Note, provided client applications are appropriately configured they need not necessarily be vulnerable to race conditions when dc_client configures this flag. The distcache(8) DC_CTX API provides additional persistence options such as fork(2)-checking and resistance against idle timeouts. Ie. if a request is commenced on a client connection that is in the process of being timed-out by dc_client, the DC_CTX will allow one retry with an immediate re-connection before considering the operation to have failed.

-pidfile path

This is a standard flag for many programs, and most useful in combination with -daemon. When -pidfile is specified dc_client will write its process ID to a file at the specified path upon successful initialisation. To use this path file to later kill the running dc_client instance, use something like (where pidfile.pid is whatever path was);

    kill `cat pidfile.pid`

-h, -help, -?

Any of these flags will cause dc_client to display a brief usage summary to the console and exit cleanly. Any other flags are ignored.

AUTHOR

This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at geoff [at] geoffthorpe.net.

Home Page: http://www.distcache.org