tlsproxy

title: tlsproxy(8)

text:
# tlsproxy(8)

## NAME
tlsproxy - Postfix TLS proxy

## SYNOPSIS

```
tlsproxy [generic Postfix daemon options]
```

## DESCRIPTION

The tlsproxy(8) server implements a two-way TLS proxy. It is used by the postscreen(8) server to talk SMTP-over-TLS with remote SMTP clients that are not allowlisted (including clients whose allowlist status has expired), and by the smtp(8) client to support TLS connection reuse, but it should also work for non-SMTP protocols.

Although one tlsproxy(8) process can serve multiple sessions at the same time, it is a good idea to allow the number of processes to increase with load, so that the service remains responsive.

## PROTOCOL EXAMPLE

```

```

The example below concerns postscreen(8). However, the tlsproxy(8) server is agnostic of the application protocol, and the example is easily adapted to other applications.

After receiving a valid remote SMTP client STARTTLS command, the postscreen(8) server sends the remote SMTP client endpoint string, the requested role (server), and the requested timeout to tlsproxy(8). postscreen(8) then receives a "TLS available" indication from tlsproxy(8). If the TLS service is available, postscreen(8) sends the remote SMTP client file descriptor to tlsproxy(8), and sends the plaintext 220 greeting to the remote SMTP client. This triggers TLS negotiations between the remote SMTP client and tlsproxy(8). Upon completion of the TLS-level handshake, tlsproxy(8) translates between plaintext from/to postscreen(8) and ciphertext to/from the remote SMTP client.

## SECURITY

```

```

The tlsproxy(8) server is moderately security-sensitive. It talks to untrusted clients on the network. The process can be run chrooted at fixed low privilege.

## DIAGNOSTICS

Problems and transactions are logged to syslogd(8) or postlogd(8).

## CONFIGURATION PARAMETERS

```

```

Changes to main.cf are not picked up automatically, as tlsproxy(8) processes may run for a long time depending on mail server load. Use the command "postfix reload" to speed up a change.

The text below provides only a parameter summary. See postconf(5) for more details including examples.

## STARTTLS GLOBAL CONTROLS

```

```

The following settings are global and therefore cannot be overruled by information specified in a tlsproxy(8) client request.

tls_append_default_CA (no)

Append the system-supplied default Certification Authority certificates to the ones specified with *_tls_CApath or *_tls_CAfile.

tls_daemon_random_bytes (32)

The number of pseudo-random bytes that an smtp(8) or smtpd(8) process requests from the tlsmgr(8) server in order to seed its internal pseudo random number generator (PRNG).

tls_high_cipherlist (see 'postconf -d' output)

The OpenSSL cipherlist for "high" grade ciphers.

tls_medium_cipherlist (see 'postconf -d' output)

The OpenSSL cipherlist for "medium" or higher grade ciphers.

tls_low_cipherlist (see 'postconf -d' output)

The OpenSSL cipherlist for "low" or higher grade ciphers.

tls_export_cipherlist (see 'postconf -d' output)

The OpenSSL cipherlist for "export" or higher grade ciphers.

tls_null_cipherlist (eNULL:!aNULL)

The OpenSSL cipherlist for "NULL" grade ciphers that provide authentication without encryption.

tls_eecdh_strong_curve (prime256v1)

The elliptic curve used by the Postfix SMTP server for sensibly strong ephemeral ECDH key exchange.

tls_eecdh_ultra_curve (secp384r1)

The elliptic curve used by the Postfix SMTP server for maximally strong ephemeral ECDH key exchange.

tls_disable_workarounds (see 'postconf -d' output)

List or bit-mask of OpenSSL bug work-arounds to disable.

tls_preempt_cipherlist (no)

With SSLv3 and later, use the Postfix SMTP server's cipher preference order instead of the remote client's cipher preference order.

Available in Postfix version 2.9 and later:

tls_legacy_public_key_fingerprints (no)

A temporary migration aid for sites that use certificate public-key fingerprints with Postfix 2.9.0..2.9.5, which use an incorrect algorithm.

Available in Postfix version 2.11-3.1:

tls_dane_digest_agility (on)

Configure RFC7671 DANE TLSA digest algorithm agility.

tls_dane_trust_anchor_digest_enable (yes)

Enable support for RFC 6698 (DANE TLSA) DNS records that contain digests of trust-anchors with certificate usage "2".

Available in Postfix version 2.11 and later:

tlsmgr_service_name (tlsmgr)

The name of the tlsmgr(8) service entry in master.cf.

Available in Postfix version 3.0 and later:

tls_session_ticket_cipher (Postfix >= 3.0: aes-256-cbc, Postfix < 3.0: aes-128-cbc)

Algorithm used to encrypt RFC5077 TLS session tickets.

openssl_path (openssl)

The location of the OpenSSL command line program openssl(1).

Available in Postfix version 3.2 and later:

tls_eecdh_auto_curves (see 'postconf -d' output)

The prioritized list of elliptic curves supported by the Postfix SMTP client and server.

Available in Postfix version 3.4 and later:

tls_server_sni_maps (empty)

Optional lookup tables that map names received from remote SMTP clients via the TLS Server Name Indication (SNI) extension to the appropriate keys and certificate chains.

Available in Postfix 3.5, 3.4.6, 3.3.5, 3.2.10, 3.1.13 and later:

tls_fast_shutdown_enable (yes)

A workaround for implementations that hang Postfix while shutting down a TLS session, until Postfix times out.

## STARTTLS SERVER CONTROLS

```

```

These settings are clones of Postfix SMTP server settings. They allow tlsproxy(8) to load the same certificate and private key information as the Postfix SMTP server, before dropping privileges, so that the key files can be kept read-only for root. These settings can currently not be overruled by information in a tlsproxy(8) client request, but that limitation may be removed in a future version.

tlsproxy_tls_CAfile ($smtpd_tls_CAfile)

A file containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates.

tlsproxy_tls_CApath ($smtpd_tls_CApath)

A directory containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates.

tlsproxy_tls_always_issue_session_ids ($smtpd_tls_always_issue_session_ids)

Force the Postfix tlsproxy(8) server to issue a TLS session id, even when TLS session caching is turned off.

tlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)

Ask a remote SMTP client for a client certificate.

tlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)

The verification depth for remote SMTP client certificates.

tlsproxy_tls_cert_file ($smtpd_tls_cert_file)

File with the Postfix tlsproxy(8) server RSA certificate in PEM format.

tlsproxy_tls_ciphers ($smtpd_tls_ciphers)

The minimum TLS cipher grade that the Postfix tlsproxy(8) server will use with opportunistic TLS encryption.

tlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)

File with the Postfix tlsproxy(8) server DSA certificate in PEM format.

tlsproxy_tls_dh1024_param_file ($smtpd_tls_dh1024_param_file)

File with DH parameters that the Postfix tlsproxy(8) server should use with non-export EDH ciphers.

tlsproxy_tls_dh512_param_file ($smtpd_tls_dh512_param_file)

File with DH parameters that the Postfix tlsproxy(8) server should use with export-grade EDH ciphers.

tlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)

File with the Postfix tlsproxy(8) server DSA private key in PEM format.

tlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)

File with the Postfix tlsproxy(8) server ECDSA certificate in PEM format.

tlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)

File with the Postfix tlsproxy(8) server ECDSA private key in PEM format.

tlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)

The Postfix tlsproxy(8) server security grade for ephemeral elliptic-curve Diffie-Hellman (EECDH) key exchange.

tlsproxy_tls_exclude_ciphers ($smtpd_tls_exclude_ciphers)

List of ciphers or cipher types to exclude from the tlsproxy(8) server cipher list at all TLS security levels.

tlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)

The message digest algorithm to construct remote SMTP client-certificate fingerprints.

tlsproxy_tls_key_file ($smtpd_tls_key_file)

File with the Postfix tlsproxy(8) server RSA private key in PEM format.

tlsproxy_tls_loglevel ($smtpd_tls_loglevel)

Enable additional Postfix tlsproxy(8) server logging of TLS activity.

tlsproxy_tls_mandatory_ciphers ($smtpd_tls_mandatory_ciphers)

The minimum TLS cipher grade that the Postfix tlsproxy(8) server will use with mandatory TLS encryption.

tlsproxy_tls_mandatory_exclude_ciphers ($smtpd_tls_mandatory_exclude_ciphers)

Additional list of ciphers or cipher types to exclude from the tlsproxy(8) server cipher list at mandatory TLS security levels.

tlsproxy_tls_mandatory_protocols ($smtpd_tls_mandatory_protocols)

The SSL/TLS protocols accepted by the Postfix tlsproxy(8) server with mandatory TLS encryption.

tlsproxy_tls_protocols ($smtpd_tls_protocols)

List of TLS protocols that the Postfix tlsproxy(8) server will exclude or include with opportunistic TLS encryption.

tlsproxy_tls_req_ccert ($smtpd_tls_req_ccert)

With mandatory TLS encryption, require a trusted remote SMTP client certificate in order to allow TLS connections to proceed.

tlsproxy_tls_security_level ($smtpd_tls_security_level)

The SMTP TLS security level for the Postfix tlsproxy(8) server; when a non-empty value is specified, this overrides the obsolete parameters smtpd_use_tls and smtpd_enforce_tls.

tlsproxy_tls_chain_files ($smtpd_tls_chain_files)

Files with the Postfix tlsproxy(8) server keys and certificate chains in PEM format.

## STARTTLS CLIENT CONTROLS

```

```

These settings are clones of Postfix SMTP client settings. They allow tlsproxy(8) to load the same certificate and private key information as the Postfix SMTP client, before dropping privileges, so that the key files can be kept read-only for root. Some settings may be overruled by information in a tlsproxy(8) client request.

Available in Postfix version 3.4 and later:

tlsproxy_client_CAfile ($smtp_tls_CAfile)

A file containing CA certificates of root CAs trusted to sign either remote TLS server certificates or intermediate CA certificates.

tlsproxy_client_CApath ($smtp_tls_CApath)

Directory with PEM format Certification Authority certificates that the Postfix tlsproxy(8) client uses to verify a remote TLS server certificate.

tlsproxy_client_chain_files ($smtp_tls_chain_files)

Files with the Postfix tlsproxy(8) client keys and certificate chains in PEM format.

tlsproxy_client_cert_file ($smtp_tls_cert_file)

File with the Postfix tlsproxy(8) client RSA certificate in PEM format.

tlsproxy_client_key_file ($smtp_tls_key_file)

File with the Postfix tlsproxy(8) client RSA private key in PEM format.

tlsproxy_client_dcert_file ($smtp_tls_dcert_file)

File with the Postfix tlsproxy(8) client DSA certificate in PEM format.

tlsproxy_client_dkey_file ($smtp_tls_dkey_file)

File with the Postfix tlsproxy(8) client DSA private key in PEM format.

tlsproxy_client_eccert_file ($smtp_tls_eccert_file)

File with the Postfix tlsproxy(8) client ECDSA certificate in PEM format.

tlsproxy_client_eckey_file ($smtp_tls_eckey_file)

File with the Postfix tlsproxy(8) client ECDSA private key in PEM format.

tlsproxy_client_fingerprint_digest ($smtp_tls_fingerprint_digest)

The message digest algorithm used to construct remote TLS server certificate fingerprints.

tlsproxy_client_loglevel ($smtp_tls_loglevel)

Enable additional Postfix tlsproxy(8) client logging of TLS activity.

tlsproxy_client_loglevel_parameter (smtp_tls_loglevel)

The name of the parameter that provides the tlsproxy_client_loglevel value.

tlsproxy_client_scert_verifydepth ($smtp_tls_scert_verifydepth)

The verification depth for remote TLS server certificates.

tlsproxy_client_security_level ($smtp_tls_security_level)

The default TLS security level for the Postfix tlsproxy(8) client.

tlsproxy_client_policy_maps ($smtp_tls_policy_maps)

Optional lookup tables with the Postfix tlsproxy(8) client TLS security policy by next-hop destination.

tlsproxy_client_use_tls ($smtp_use_tls)

Opportunistic mode: use TLS when a remote server announces TLS support.

tlsproxy_client_enforce_tls ($smtp_enforce_tls)

Enforcement mode: require that SMTP servers use TLS encryption.

tlsproxy_client_per_site ($smtp_tls_per_site)

Optional lookup tables with the Postfix tlsproxy(8) client TLS usage policy by next-hop destination and by remote TLS server hostname.

## OBSOLETE STARTTLS SUPPORT CONTROLS

```

```

These parameters are supported for compatibility with smtpd(8) legacy parameters.

tlsproxy_use_tls ($smtpd_use_tls)

Opportunistic TLS: announce STARTTLS support to remote SMTP clients, but do not require that clients use TLS encryption.

tlsproxy_enforce_tls ($smtpd_enforce_tls)

Mandatory TLS: announce STARTTLS support to remote SMTP clients, and require that clients use TLS encryption.

## RESOURCE CONTROLS

```

```

tlsproxy_watchdog_timeout (10s)

How much time a tlsproxy(8) process may take to process local or remote I/O before it is terminated by a built-in watchdog timer.

## MISCELLANEOUS CONTROLS

```

```

config_directory (see 'postconf -d' output)

The default location of the Postfix main.cf and master.cf configuration files.

process_id (read-only)

The process ID of a Postfix command or daemon process.

process_name (read-only)

The process name of a Postfix command or daemon process.

syslog_facility (mail)

The syslog facility of Postfix logging.

syslog_name (see 'postconf -d' output)

A prefix that is prepended to the process name in syslog records, so that, for example, "smtpd" becomes "prefix/smtpd".

Available in Postfix 3.3 and later:

service_name (read-only)

The master.cf service name of a Postfix daemon process.

## SEE ALSO

```
postscreen(8), Postfix zombie blocker
smtpd(8), Postfix SMTP server
postconf(5), configuration parameters
postlogd(8), Postfix logging
syslogd(8), system logging
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

This service was introduced with Postfix version 2.8.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


pgpool

title: pgpool(8)

summary: Pgpool\-II main server

text:
# pgpool(8)

## NAME
pgpool - Pgpool-II main server

## SYNOPSIS
pgpool [option...]

pgpool [option...] stop

pgpool [option...] reload

## DESCRIPTION
the Pgpool-II main server

## USAGES
pgpool runs in 3 modes: start, stop and reload. If none of stop or reload is given, it is assumed that "start" is specified.

## COMMON OPTIONS
These are common options for 3 modes.

-a hba_config_file

--hba-file=hba_config_file

Set the path to the pool_hba.conf configuration file. Mandatory if the file is placed other than the standard location.

-f config_file

--config-file=config_file

Set the path to the pgpool.conf configuration file. Mandatory if the file is placed other than the standard location.

-F pc_config_file

--pcp-file=pcp_config_file

Set the path to the pcp.conf configuration file. Mandatory if the file is placed other than the standard location.

-k key_file

--key-file=key_file

Set the path to the .pgpoolkey file. Mandatory if you use AES256 encrypted password and the file is placed other than the standard location and used.

-h

--help

Print help.

## STARTING PGPOOL-II MAIN SERVER
Here are options for the start mode.

-d

--debug

Run Pgpool-II in debug mode. Lots of debug messages are produced.

-n

--dont-detach

Don't run in daemon mode, does not detach control ttys.

-x

--debug-assertions

Turns on various assertion checks, This is a debugging aid.

-C

--clear-oidmaps

Clear query cache oidmaps when memqcache_method is memcached. If memqcache_method is shmem, Pgpool-II always discards oidmaps at the start-up time. So this option is not necessary.

-D

--discard-status

Discard pgpool_status file and do not restore previous status.

Caution

This option is testing purpose only for developers and you should not use it for other purposes. If pgpool_status is accidentally removed, Pgpool-II may go into split-brain (there are multiple primary servers exist).

## STOPPING PGPOOL-II MAIN SERVER
Here are options for the stop mode.

-m shutdown_mode

--mode=shutdown_mode

Stop Pgpool-II. shutdown_mode is either smart, fast or immediate. If smart is specified, Pgpool-II will wait for all clients are disconnected. If fast or immediate are specified, Pgpool-II immediately stops itself without waiting for all clients are disconnected. There's no difference between fast and immediate in the current implementation.

## RELOADING PGPOOL-II CONFIGURATION FILES
Reload configuration file of Pgpool-II. No specific options exist for reload mode. Common options are applicable.


pound

package: pound

title: pound(8)

text:
# pound(8)

## NAME
pound - HTTP/HTTPS reverse-proxy and load-balancer

## SYNOPSIS
pound

[-v] [-c] [-V] [-f config_file] [-p pid_file]

## DESCRIPTION
Pound is a reverse-proxy load balancing server. It accepts requests from HTTP/HTTPS clients and distributes them to one or more Web servers. The HTTPS requests are decrypted and passed to the back-ends as plain HTTP.

If more than one back-end server is defined, Pound chooses one of them randomly, based on defined priorities. By default, Pound keeps track of associations between clients and back-end servers (sessions).

## GENERAL PRINCIPLES
In general Pound needs three types of objects defined in order to function: listeners, services and back-ends.

Listeners

A listener is a definition of how Pound receives requests from the clients (browsers). Two types of listeners may be defined: regular HTTP listeners and HTTPS (HTTP over SSL/TLS) listeners. At the very least a listener must define the address and port to listen on, with additional requirements for HTTPS listeners.

Services

A service is the definition of how the requests are answered. The services may be defined within a listener or at the top level (global). When a request is received Pound attempts to match them to each service in turn, starting with the services defined in the listener itself and, if needed, continuing with the services defined at the global level. The services may define their own conditions as to which requests they can answer: typically this involves certain URLs (images only, or a certain path) or specific headers (such as the Host header). A service may also define a session mechanism: if defined future requests from a given client will always be answered by the same back-end.

Back-ends

The back-ends are the actual servers for the content requested. By itself, Pound supplies no responses - all contents must be received from a "real" web server. The back-end defines how the server should be contacted.

Three types of back-ends may be defined: a "regular" back-end which receives requests and returns responses, a "redirect" back-end in which case Pound will respond with a redirect response, without accessing any back-end at all, or an "emergency" back-end which will be used only if all other backends are "dead".

Multiple back-ends may be defined within a service, in which case Pound will load-balance between the available back-ends.

If a back-end fails to respond it will be considered "dead", in which case Pound will stop sending requests to it. Dead back-ends are periodically checked for availability, and once they respond again they are "resurected" and requests are sent again their way. If no back-ends are available (none were defined, or all are "dead") then Pound will reply with "503 Service Unavailable", without checking additional services.

The connection between Pound and the back-ends is always via HTTP, regardless of the actual protocol used between Pound and the client.

## OPTIONS
Options available (see also below for configuration file options):

-v

Verbose mode: error messages will be sent to stdout even if Pound was configured to log to syslog. This applies only to startup messages, before Pound puts itself in the background. Normal operational messages will still go to syslog.

-V

Print version: Pound will exit immediately after printing the current version and configuration flags.

-c

Check only: Pound will exit immediately after parsing the configuration file. This may be used for running a quick syntax check before actually activating a server.

-f config_file

Location of the configuration file (see below for a full description of the format). Default: /etc/pound.cfg

-p pid_file

Location of the pid file. Pound will write its own pid into this file. Normally this is used for shell scripts that control starting and stopping of the daemon. Default: /var/run/pound.pid

In general, any number of back-end servers may be specified. Use the priority to affect the load distribution among unequal-performance servers.

One (or more) copies of Pound should be started at boot time. Use "big iron" if you expect heavy loads: while Pound is as light-weight as I know how to make it, with a lot of simultaneous requests it will use quite a bit of CPU and memory. Multiple CPUs are your friend.

## CONFIGURATION FILE
Each line in the file is considered a complete configuration directive. The directives are case-insensitive. Empty lines or lines starting in '#' are ignored. There are three types of directives: global directives (they affect the settings for the entire program instance), listener directives (they define which requests Pound will listen for), and service directives (they affect only a specific group of requests).

## GLOBAL DIRECTIVES
Global directives may appear anywhere within the configuration file, though it is customary for them to be at the start. They may appear in any order.

User "user_name"

Specify the user Pound will run as (must be defined in /etc/passwd).

Group "group_name"

Specify the group Pound will run as (must be defined in /etc/group).

RootJail "directory_path_and_name"

Specify the directory that Pound will chroot to at runtime. Please note that OpenSSL requires access to /dev/urandom, so make sure you create a device by that name, accessible from the root jail directory. Pound may also require access to /dev/syslog or similar.

Daemon 0|1

Have Pound run in the foreground (if 0) or as a daemon (if 1). By default Pound runs as a daemon (detaches itself from the controlling terminal and puts itself in the background). By specifying this option you can force Pound to work like a regular process. Useful for debugging or if you want to use something like daemontools.

Threads nnn

How many worker threads Pound should use. Default: 128. Tune this parameter to improve performance. If you set it too high, Pound will use a lot memory, and some CPU will be wasted on context switches. If you set it too low requests may be served with some delay. Experiment to find the optimal value for your installation.

LogFacility value

Specify the log facility to use. value (default: daemon) must be one of the symbolic facility names defined in syslog.h. This facility shall be used for logging. Using a - for the facility name causes Pound to log to stdout/stderr.

LogLevel value

Specify the logging level: 0 for no logging, 1 (default) for regular logging, 2 for extended logging (show chosen backend server as well), 3 for Apache-like format (Combined Log Format with Virtual Host), 4 (same as 3 but without the virtual host information) and 5 (same as 4 but with information about the Service and BackEnd used). This value can be overridden for specific listeners.

IgnoreCase 0|1

Ignore case when matching URLs (default: 0). This value can be overridden for specific services.

Alive value

Specify how often Pound will check for resurected back-end hosts (default: 30 seconds). In general, it is a good idea to set this as low as possible - it will find resurected hosts faster. However, if you set it too low it will consume resources - so beware.

Client value

Specify for how long Pound will wait for a client request (default: 10 seconds). After this long has passed without the client sending any data Pound will close the connection. Set it higher if your clients time-out on a slow network or over-loaded server, lower if you start getting DOS attacks or run into problems with IE clients. This value can be overridden for specific listeners.

TimeOut value

How long should Pound wait for a response from the back-end (in seconds). Default: 15 seconds. This value can be overridden for specific back-ends.

ConnTO value

How long should Pound wait for a connection to the back-end (in seconds). Default: the TimeOut value. This value can be overridden for specific back-ends.

Grace value

How long should Pound continue to answer existing connections after a receiving and INT or HUP signal (default: 30 seconds). The configured listeners are closed immediately. You can bypass this behaviour by stopping Pound with a TERM or QUIT signal, in which case the program exits without any delay.

SSLEngine "name"

Use an OpenSSL hardware acceleration card called name. Available only if OpenSSL-engine is installed on your system.

ECDHcurve "name"

Use the named curve for elliptical curve encryption (default: prime256v1).

Control "/path/to/socket"

Set the control socket path. If not defined Pound does not listen for any commands. The commands may be issued by using the poundctl(8) program.

Include "/path/to/file"

Include the file as though it were part of the configuration file.

Anonymise

Replace the last byte of the client address with 0 for logging purposes. Default: log the client address in full.

## HTTP Listener
An HTTP listener defines an address and port that Pound will listen on for HTTP requests. All configuration directives enclosed between ListenHTTP and End are specific to a single HTTP listener. At the very least you must specify and address and a port for each listener. The following directives are available:

Address address

The address that Pound will listen on. This can be a numeric IP address, or a symbolic host name that must be resolvable at run-time. This is a mandatory parameter. The address 0.0.0.0 may be used as an alias for 'all available addresses on this machine', but this practice is strongly discouraged, as it will interfere with the rewriting mechanisms (see below).

Port port

The port number that Pound will listen on. This is a mandatory parameter.

xHTTP value

Defines which HTTP verbs are accepted. The possible values are:

0 (default) accept only standard HTTP requests (GET, POST, HEAD).

1 additionally allow extended HTTP requests (PUT, PATCH, DELETE).

2 additionally allow standard WebDAV verbs (LOCK, UNLOCK, PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY, CHECKOUT, MERGE, REPORT).

3 additionally allow MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).

4 additionally allow MS RPC extensions verbs (RPC_IN_DATA, RPC_OUT_DATA).

Client value

Override the global Client time-out value.

CheckURL "pattern to match"

Define a pattern that must be matched by each request sent to this listener. A request that does not match is considered to be illegal. By default Pound accepts all requests (i.e. the pattern is ".*"), but you are free to limit it to something more reasonable. Please note that this applies only to the request path - Pound will still check that the request is syntactically correct.

Err414 "filename"

A file with the text to be displayed if an Error 414 occurs. Default: "Request URI is too long.".

Err500 "filename"

A file with the text to be displayed if an Error 500 occurs. Default: "An internal server error occurred. Please try again later.".

Err501 "filename"

A file with the text to be displayed if an Error 501 occurs. Default: "This method may not be used.".

Err503 "filename"

A file with the text to be displayed if an Error 503 occurs. Default: "The service is not available. Please try again later.".

MaxRequest nnn

Request maximal size. All requests will be limited to these many bytes. If a request contains more data than allowed an error 414 is returned. Default: unlimited.

HeadRemove "header pattern"

Remove certain headers from the incoming requests. All occurences of the matching specified header will be removed. Please note that this filtering is done prior to other checks (such as HeadRequire or HeadDeny), so you should not try to check for these headers in later matches. Multiple directives may be specified in order to remove more than one header, and the header itself may be a regular pattern (though this should be used with caution).

AddHeader "header: to add"

Add the defined header to the request passed to the back-end server. The header is added verbatim. Use multiple AddHeader directives if you need to add more than one header.

RewriteLocation 0|1|2

If 1 force Pound to change the Location: and Content-location: headers in responses. If they point to the back-end itself or to the listener (but with the wrong protocol) the response will be changed to show the virtual host in the request. Default: 1 (active). If the value is set to 2 only the back-end address is compared; this is useful for redirecting a request to an HTTPS listener on the same server as the HTTP listener.

RewriteDestination 0|1

If 1 force Pound to change the Destination: header in requests. The header is changed to point to the back-end itself with the correct protocol. Default: 0.

LogLevel value

Override the global LogLevel value.

Service [ "name" ]

This defines a private service (see below for service definition syntax). This service will be used only by this listener. The service may be optionally named, with the name showing in the poundctl listings.

## HTTPS Listener
An HTTPS listener defines an address and port that Pound will listen on for HTTPS requests. All configuration directives enclosed between ListenHTTPS and End are specific to a single HTTPS listener. At the very least you must specify and address, a port and a server certificate for each listener. All directives defined for HTTP listeners are applicable to HTTPS listeners as well. The following additional directives are also available:

Cert "certificate file"

Specify the server certificate. The certificate file is the file containing the certificate, possibly a certificate chain and the signature for this server. This directive is mandatory for HTTPS listeners.

Please note that multiple Cert directives are allowed if your OpenSSL version supports SNI. In such cases, the first directive is the default certificate, with additional certificates used if the client requests them.

The ordering of the directives is important: the first certificate where the CN matches the client request will be used, so put your directives in the most-specific-to-least specific order (i.e. wildcard certificates after host-specific certificates).

Cert directives must precede all other SSL-specific directives.

ClientCert 0|1|2|3 depth

Ask for the client's HTTPS certificate: 0 - don't ask (default), 1 - ask, 2 - ask and fail if no certificate was presented, 3 - ask but do not verify. Depth is the depth of verification for a client certificate (up to 9). The default depth limit is 9, allowing for the peer certificate and additional 9 CA certificates that must be verified.

Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2

Disable the protocol and all lower protocols as well. This is due to a limitation in OpenSSL, which does not support disabling a single protocol. For example, Disable TLSv1 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.

Ciphers "acceptable:cipher:list"

This is the list of ciphers that will be accepted by the SSL connection; it is a string in the same format as in OpenSSL ciphers(1) and SSL_CTX_set_cipher_list(3).

SSLHonorCipherOrder 0|1

If this value is 1, the server will broadcast a preference to use Ciphers in the order supplied in the Ciphers directive. If the value is 0, the server will treat the Ciphers list as the list of Ciphers it will accept, but no preference will be indicated. Default value is 0.

SSLAllowClientRenegotiation 0|1|2

If this value is 0, client initiated renegotiation will be disabled. This will mitigate DoS exploits based on client renegotiation, regardless of the patch status of clients and servers related to "Secure renegotiation". If the value is 1, secure renegotiation is supported. If the value is 2, insecure renegotiation is supported, with unpatched clients. This can lead to a DoS and a Man in the Middle attack! The default value is 0.

CAlist "CAcert_file"

Set the list of "trusted" CA's for this server. The CAcert_file is a file containing a sequence of CA certificates (PEM format). The names of the defined CA certificates will be sent to the client on connection.

VerifyList "Verify_file"

Set the CA (Certificate Authority). The Verify_file is a file that contains the CA root certificates (in PEM format).

Please note: there is an important difference between the CAlist and the VerifyList. The CAlist tells the client (browser) which client certificates it should send. The VerifyList defines which CAs are actually used for the verification of the returned certificate.

CRLlist "CRL_file"

Set the CRL (Certificate Revocation List) file. The CRL_file is a file that contains the CRLs (in PEM format).

NoHTTPS11 0|1|2

Behave like an HTTP/1.0 server for HTTPS clients. If this value is 0 disable the check. If the value is 1 do not allow multiple requests on SSL connections. If the value is 2 (default) disable multiple requests on SSL connections only for MSIE clients. Required work-around for a bug in certain versions of IE.

## Service
A service is a definition of which back-end servers Pound will use to reply to incoming requests. A service may be defined as part of a listener (in which case it will be used only by that listener), or globally (which makes it available to all listeners). Pound will always try the private services in the order defined, followed by the global ones.

All configuration directives enclosed between Service and End are specific to a single service. The following directives are available:

URL "pattern"

Match the incoming request. If a request fails to match than this service will be skipped and next one tried. If all services fail to match Pound returns an error. You may define multiple URL conditions per service, in which case all patterns must match. If no URL was defined then all requests match. The matching is by default case-sensitive, but this can be overridden by specifying IgnoreCase 1

IgnoreCase 0|1

Override the global IgnoreCase setting.

HeadRequire "pattern"

The request must contain at least on header matching the given pattern. Multiple HeadRequire directives may be defined per service, in which case all of them must be satisfied.

HeadDeny "pattern"

The request may not contain any header matching the given pattern. Multiple HeadDeny directives may be defined per service, in which case all of them must be satisfied.

Please note: if the listener defined a HeadRemove directive, the matching headers are removed before the service matching is attempted.

Disabled 0|1

Start Pound with this service disabled (1) or enabled (0). If started as disabled, the service can be later enabled with poundctl (8).

BackEnd

Directives enclosed between a BackEnd and the following End directives define a single back-end server (see below for details). You may define multiple back-ends per service, in which case Pound will attempt to load-balance between them.

Redirect [code] "url"

This is a special type of back-end. Instead of sending the request to a back-end Pound replies immediately with a redirection to the given URL. You may define multiple redirectors in a service, as well as mixing them with regular back-ends.

The address the client is redirected to is determined by the actual url you specify: if it is a "pure" host (i.e. with no path) then the client will be redirected to the host you specified, with the original request path appended. If your url does contain a path then the request path is ignored.

Examples: if you specified

Redirect "http://abc.example"

and the client requested http://xyz/a/b/c then it will be redirected to http://abc.example/a/b/c, but if you specified

Redirect "http://abc.example/index.html"

it will be sent to http://abc.example/index.html.

Technical note: in an ideal world Pound should reply with a "307 Temporary Redirect" status. Unfortunately, that is not yet supported by all clients (in particular HTTP 1.0 ones), so Pound currently replies by default with a "302 Found" instead. You may override this behaviour by specifying the code to be used (301, 302 or 307).

Emergency

Directives enclosed between an Emergency and the following End directives define an emergency back-end server (see below for details). You may define only one emergency server per service, which Pound will attempt to use if all backends are down.

Session

Directives enclosed between a Session and the following End directives define a session-tracking mechanism for the current service. See below for details.

## BackEnd
A back-end is a definition of a single back-end server Pound will use to reply to incoming requests. All configuration directives enclosed between BackEnd and End are specific to a single service. The following directives are available:

Address address

The address that Pound will connect to. This can be a numeric IP address, or a symbolic host name that must be resolvable at run-time. If the name cannot be resolved to a valid address, Pound will assume that it represents the path for a Unix-domain socket. This is a mandatory parameter.

Port port

The port number that Pound will connect to. This is a mandatory parameter for non Unix-domain back-ends.

HTTPS

The back-end is using HTTPS.

Cert "certificate file"

Specify the certificate that Pound will use as a client. The certificate file is the file containing the certificate, possibly a certificate chain and the signature. This directive may appear only after the HTTPS directive.

Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2

Disable the protocol and all lower protocols as well. This is due to a limitation in OpenSSL, which does not support disabling a single protocol. For example, Disable TLSv1 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2. This directive may appear only after the HTTPS directive.

Ciphers "acceptable:cipher:list"

This is the list of ciphers that will be accepted by the SSL connection; it is a string in the same format as in OpenSSL ciphers(1) and SSL_CTX_set_cipher_list(3). This directive may appear only after the HTTPS directive.

Priority val

The priority of this back-end (between 1 and 9, 5 is default). Higher priority back-ends will be used more often than lower priority ones, so you should define higher priorities for more capable servers.

TimeOut val

Override the global TimeOut value.

ConnTO val

Override the global ConnTO value.

HAport [ address ] port

A port (and optional address) to be used for server function checks. See below the "High Availability" section for a more detailed discussion. By default Pound uses the same address as the back-end server, but you may use a separate address if you wish. This directive applies only to non Unix-domain servers.

Disabled 0|1

Start Pound with this back-end disabled (1) or enabled (0). If started as disabled, the back-end can be later enabled with poundctl (8).

## Emergency
The emergency server will be used once all existing back-ends are "dead". All configuration directives enclosed between Emergency and End are specific to a single service. The following directives are available:

Address address

The address that Pound will connect to. This can be a numeric IP address, or a symbolic host name that must be resolvable at run-time. If the name cannot be resolved to a valid address, Pound will assume that it represents the path for a Unix-domain socket. This is a mandatory parameter.

Port port

The port number that Pound will connect to. This is a mandatory parameter for non Unix-domain back-ends.

## Session
Defines how a service deals with possible HTTP sessions. All configuration directives enclosed between Session and End are specific to a single service. Once a sessions is identified, Pound will attempt to send all requests within that session to the same back-end server.

The following directives are available:

Type IP|BASIC|URL|PARM|COOKIE|HEADER

What kind of sessions are we looking for: IP (the client address), BASIC (basic authentication), URL (a request parameter), PARM (a URI parameter), COOKIE (a certain cookie), or HEADER (a certain request header). This is a mandatory parameter.

TTL seconds

How long can a session be idle (in seconds). A session that has been idle for longer than the specified number of seconds will be discarded. This is a mandatory parameter.

ID "name"

The session identifier. This directive is permitted only for sessions of type URL (the name of the request parameter we need to track), COOKIE (the name of the cookie) and HEADER (the header name).

See below for some examples.

## HIGH-AVAILABILITY
Pound attempts to keep track of active back-end servers, and will temporarily disable servers that do not respond (though not necessarily dead: an overloaded server that Pound cannot establish a connection to will be considered dead). However, every Alive seconds, an attempt is made to connect to the dead servers in case they have become active again. If this attempt succeeds, connections will be initiated to them again.

In general it is a good idea to set this time interval as low as is consistent with your resources in order to benefit from resurected servers at the earliest possible time. The default value of 30 seconds is probably a good choice.

The clients that happen upon a dead backend server will just receive a 503 Service Unavailable message.

The HAport parameter specifies an additional port (and optionally an address) that is used only for viability checks: if this port is specified in a BackEnd directive, Pound will attempt periodically (every Alive seconds) to connect to this port. If the port does not respond the server is considered dead. It never makes sense to have the HAport identical to the main back-end port: this would only generate extra, unncecessary activity (CPU, network traffic) for no good reason whatsoever. The HAport is meant for applications that offer an additional health monitoring port or for installations that wish to take servers off-line in a controlled manner.

By default the address of the HAport health monitor is the same as that of the back-end server. You may specify a different address though, for example if you have a monitoring program running on another host.

## HTTPS HEADERS
If a client browser connects to Pound via HTTPS and if it presents a client certificate Pound adds the following headers to the request it issues to the server:

X-SSL-Subject

Details about the certificate owner.

X-SSL-Issuer

Details about the certificate issuer (Certificate Authority).

X-SSL-notBefore

Starting date of certificate validity.

X-SSL-notAfter

Ending date of certificate validity.

X-SSL-serial

Certificate serial number (decimal).

X-SSL-cipher

The cipher currently in use.

X-SSL-certificate

The full client certificate (PEM-format multi-line)

It is the application's responsibility to actually use these headers - Pound just passes this information without checking it in any way (except for signature and encryption correctness).

## SECURITY
In general, Pound does not read or write to the hard-disk. The exceptions are reading the configuration file and (possibly) the server certificate file(s) and error message(s), which are opened read-only on startup, read, and closed, and the pid file which is opened on start-up, written to and immediately closed. Following this there is no disk access whatsoever, so using a RootJail directive is only for extra security bonus points.

Pound tries to sanitise all HTTP/HTTPS requests: the request itself, the headers and the contents are checked for conformance to the RFC's and only valid requests are passed to the back-end servers. This is not absolutely fool-proof - as the recent Apache problem with chunked transfers demonstrated. However, given the current standards, this is the best that can be done - HTTP is an inherently weak protocol.

## ADDITIONAL NOTES
Pound uses the system log for messages (default facility LOG_DAEMON). The format is very similar to other web servers, so that if you want to use a log tool:

fgrep pound /var/log/messages | your_log_tool

Translating HTTPS to HTTP is an iffy proposition: no client information is passed to the server itself (certificates, etc) and the backend server may be misled if it uses absolute URLs. A patch for Zope is included in the distribution to address this issue - for other Web servers you are on your own. May the source be with you.

Pound deals with (and sanitizes) HTTP/1.1 requests. Thus even if you have an HTTP/1.0 server, a single connection to an HTTP/1.1 client is kept, while the connection to the back-end server is re-opened as necessary.

Pound attempts to resolve the names of the hosts that appear in various requests and/or responses. That means it need a functioning resolver of some kind (be it /etc/hosts, DNS or something else).

## EXAMPLES
To translate HTTPS requests to a local HTTP server (assuming your network address is 123.123.123.123):

ListenHTTPS

Address 1.2.3.4

Port 443

Cert "/etc/pound/server.pem"

Service

BackEnd

Address 127.0.0.1

Port 80

End

End

End

To distribute the HTTP/HTTPS requests to three Web servers, where the third one is a newer and faster machine:

ListenHTTP

Address 123.123.123.123

Port 80

End

ListenHTTPS

Address 1.2.3.4

Port 443

Cert "/etc/pound/server.pem"

End Service

BackEnd

Address 192.168.0.10

Port 80

End

BackEnd

Address 192.168.0.11

Port 80

End

BackEnd

Address 192.168.0.12

Port 80

Priority 3

End

End

To separate between image requests and other Web content and send all requests for a specific URL to a secure server:

ListenHTTP

Address 123.123.123.123

Port 80

End # Images server(s)

Service

URL ".*.(jpg|gif)"

BackEnd

Address 192.168.0.12

Port 80

End

End

\# redirect all requests for /forbidden

Service

Url "/forbidden.*"

Redirect "https://xyzzy.com"

End

\# Catch-all server(s)

Service

BackEnd

Address 192.168.0.10

Port 80

End

BackEnd

Address 192.168.0.11

Port 80

End

Session

Type BASIC

TTL 300

End

End

Here is a more complex example: assume your static images (GIF/JPEG) are to be served from a single back-end 192.168.0.10. In addition, 192.168.0.11 is to do the hosting for www.myserver.com with URL-based sessions, and 192.168.0.20 (a 1GHz PIII) and 192.168.0.21 (800Mhz Duron) are for all other requests (cookie-based sessions). The logging will be done by the back-end servers. The configuration file may look like this:

User "nobody"

Group "nogroup"

RootJail "/var/pound/jail"

Alive 60

LogLevel 0 # Main listening ports

ListenHTTP

Address 1.2.3.4

Port 80

Client 10

End

ListenHTTPS

Address 1.2.3.4

Port 443

Cert "/etc/pound/pound.pem"

Client 20

End

\# Image server

Service

URL ".*.(jpg|gif)"

BackEnd

Address 192.168.0.10

Port 80

End

End

\# Virtual host www.myserver.com

Service

URL ".*sessid=.*"

HeadRequire "Host:.*www.myserver.com.*"

BackEnd

Address 192.168.0.11

Port 80

End

Session

Type URL

ID "sessid"

TTL 120

End

End

\# Everybody else

Service

BackEnd

Address 192.168.0.20

Port 80

Priority 5

End

BackEnd

Address 192.168.0.21

Port 80

Priority 4

End

Session

Type COOKIE

ID "userid"

TTL 180

End

End

## FILES
/var/run/pound.nnn

this is where Pound will attempt to record its process id.

/etc/pound.cfg

the default configuration file (the location may be changed when compiling - see the F_CONF flag in the Makefile).

/etc/pound/cert.pem

the certificate file(s) for HTTPS. The location must be defined in the configuration file - this is only a suggestion. The file must contain a PEM-encoded certificate, optionally a certificate chain from a known Certificate Authority to your server certificate and a PEM-encoded private key (not password protected). See OpenSSL(1) for details. This file should be well protected, lest someone gets your server private key.

## AUTHOR
Written by Robert Segall, Apsis GmbH.

## REPORTING BUGS
Report bugs to <roseg@apsis.ch>.

## COPYRIGHT
Copyright © 2002-2010 Apsis GmbH.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


poundctl

title: poundctl(8)

summary: control the pound(8) daemon

text:
# poundctl(8)

## NAME
poundctl - control the pound(8) daemon

## SYNOPSIS
poundctl -c /path/to/socket [-L/-l] [-S/-s] [-B/-b] [-N/-n] [-H] [-X]

## DESCRIPTION
Poundctl controls various aspects of the operation of the pound(8) program.

## OPTIONS
Options available:

-c /path/to/socket

The path to the (Unix-domain) socket Pound was configured to listen on for control. Your Pound configuration file must contain the directive Control /path/to/socket for poundctl to work.

-L/-l n

Enable/disable a listener. A disabled listener will stop accepting connection requests.

-S/-s n m

Enable/disable a service. A disabled service will not be used by Pound to answer requests.

-B/-b n m r

Enable/disable a back-end. A disabled back-end will not be passed requests to answer. Note however that existing sessions may still cause requests to be sent their way.

-N n m k r

Add a session to service m in listener n. The session key is k and it points to back-end r.

-n n m k

Remove a session from service m in listener n. The session key is k.

The parameters n, m and r refer to the number assigned to a particular listener, service and back-end in the listings. A listener number of -1 refers by convention to the global context.

-H

Try to resolve the addresses to symbolic names. Depending on your configuration, this may require an active DNS.

-X

Show the results in XML format.

When called without flags poundctl will print out a listing of the Pound internal state.

## AUTHOR
Written by Robert Segall, Apsis GmbH.

## REPORTING BUGS
Report bugs to <roseg@apsis.ch>.

## COPYRIGHT
Copyright © 2002-2010 Apsis GmbH.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


powertop

package: powertop

title: powertop(8)

text:
# powertop(8)

## NAME
powertop - a power consumption and power management diagnosis tool.

## SYNOPSIS
powertop [options]

## DESCRIPTION
powertop is a program that helps to diagnose various issues with power consumption and power management. It also has an interactive mode allowing one to experiment with various power management settings. When invoking powertop without arguments powertop starts in interactive mode.

## OPTIONS
--auto-tune

Set all tunable options to their good setting without interaction.

-c, --calibrate

Runs powertop in calibration mode. When running on battery, powertop can track power consumption as well as system activity. When there are enough measurements, powertop can start to report power estimates. One can get more accurate estimates by using this option to enable a calibration cycle. This will cycle through various display levels and USB device activities and workloads.

-C, --csv[=filename]

Generate a CSV report. If a filename is not specified then the default name powertop.csv is used. The CSV report can be used for reporting and data analysis.

--debug

Run in debug mode.

--extech=devnode

Use the Extech Power Analyzer for measurements. This allows one to specify the serial device node of the serial to USB adaptor connecting to the Extech Power Analyzer, for example /dev/ttyUSB0.

-r, --html[=filename]

Generate an HTML report. If a filename is not specified then the default name powertop.html is used. The HTML report can be sent to others to help diagnose power issues.

-i, --iteration[=iterations]

Number of times to run each test.

-q, --quiet

Suppress stderr output.

-t, --time[=seconds]

Generate a report for a specified number of seconds.

-w, --workload[=workload]

Execute workload file as a part of calibration before making a report.

-V, --version

Print version information and exit.

-h, --help

Show the help message and exit.

## COMMANDS
In interactive mode, the following key bindings are available:

Tab

Show next tab

BackTab

Show previous tab

Right Arrow

Scroll to the right

Left Arrow

Scroll to the left

Up Arrow, PageUp

Scroll up or select previous item

Down Arrow, PageDown

Scroll down or select next item

Space, Return

Activate current item

s

Set refresh timeout

r

Refresh window

q, Ctrl-C, Escape

Exit powertop

## BUGS
Send bug reports to powertop@lists.01.org

## SEE ALSO
The program is more fully described at https://01.org/powertop

## AUTHOR
powertop was written by Arjan van de Ven, and is currently maintained by Chris E Ferron.


title: powertop1(8)

text:
# powertop1(8)

## NAME
powertop - program to analyze power consumption on Intel-based laptops

## SYNOPSIS
powertop [-d] [-t DOUBLE ] [-p] [-h] [-v]

## DESCRIPTION
powertop is a program that shows the power consumption on Intel-based laptops and makes suggestions on how to extend battery lifetime.

## OPTIONS
-d, --dump

read wakeups once and print list of top offenders.

-t, --time=DOUBLE

default time to gather data in seconds.

-p, --pids

show pids in wakeups list.

-h, --help

show the help message.

-v, --version

show version information and exit.

## BUGS
Send bug reports to <power@bughost.org>

## SEE ALSO
The program is more fully described at http://www.lesswatts.org/projects/powertop/

## AUTHOR
powertop was written by Arjan van de Ven <arjan@linux.intel.com>, and is maintained by Auke Kok <auke@linux.intel.com>.


chat

package: ppp

title: chat(8)

text:
# chat(8)

## NAME
chat - Automated conversational script with a modem

## SYNOPSIS
chat [ options ] script

## DESCRIPTION
The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point Protocol Daemon (pppd) and the remote's pppd process.

## OPTIONS
-f <chat file>

Read the chat script from the chat file. The use of this option is mutually exclusive with the chat script parameters. The user must have read access to the file. Multiple lines are permitted in the file. Space or horizontal tab characters should be used to separate the strings.

-t <timeout>

Set the timeout for the expected string to be received. If the string is not received within the time limit then the reply string is not sent. An alternate reply may be sent or the script will fail if there is no alternate reply string. A failed script will cause the chat program to terminate with a non-zero error code.

-r <report file>

Set the file for output of the report strings. If you use the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use REPORT keywords, the stderr file is used for the report strings.

-e

Start with the echo option turned on. Echoing may also be turned on or off at specific points in the chat script by using the ECHO keyword. When echoing is enabled, all output from the modem is echoed to stderr.

-E

Enables environment variable substitution within chat scripts using the standard $xxx syntax.

-v

Request that the chat script be executed in a verbose mode. The chat program will then log the execution state of the chat script as well as all text received from the modem and the output strings sent to the modem. The default is to log through the SYSLOG; the logging method may be altered with the -S and -s flags.

-V

Request that the chat script be executed in a stderr verbose mode. The chat program will then log all text received from the modem and the output strings sent to the modem to the stderr device. This device is usually the local console at the station running the chat or pppd program.

-s

Use stderr. All log messages from '-v' and all error messages will be sent to stderr.

-S

Do not use the SYSLOG. By default, error messages are sent to the SYSLOG. The use of -S will prevent both log messages from '-v' and error messages from being sent to the SYSLOG.

-T <phone number>

Pass in an arbitrary string, usually a phone number, that will be substituted for the \T substitution metacharacter in a send string.

-U <phone number 2>

Pass in a second string, usually a phone number, that will be substituted for the \U substitution metacharacter in a send string. This is useful when dialing an ISDN terminal adapter that requires two numbers.

script

If the script is not specified in a file with the -f option then the script is included as parameters to the chat program.

## CHAT SCRIPT
The chat script defines the communications.

A script consists of one or more "expect-send" pairs of strings, separated by spaces, with an optional "subexpect-subsend" string pair, separated by a dash as in the following example:

ogin:-BREAK-ogin: ppp ssword: hello2u2

This line indicates that the chat program should expect the string "ogin:". If it fails to receive a login prompt within the time interval allotted, it is to send a break sequence to the remote and then expect the string "ogin:". If the first "ogin:" is received then the break sequence is not generated.

Once it received the login prompt the chat program will send the string ppp and then expect the prompt "ssword:". When it receives the prompt for the password, it will send the password hello2u2.

A carriage return is normally sent following the reply string. It is not expected in the "expect" string unless it is specifically requested by using the \r character sequence.

The expect sequence should contain only what is needed to identify the string. Since it is normally stored on a disk file, it should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, or other variable pieces of data as an expect string.

To help correct for characters which may be corrupted during the initial sequence, look for the string "ogin:" rather than "login:". It is possible that the leading "l" character may be received in error and you may never find the string even though it was sent by the system. For this reason, scripts look for "ogin:" rather than "login:" and "ssword:" rather than "password:".

A very simple script might look like this:

ogin: ppp ssword: hello2u2

In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.

In actual practice, simple scripts are rare. At the vary least, you should include sub-expect sequences should the original string not be received. For example, consider the following script:

ogin:--ogin: ppp ssword: hello2u2

This would be a better script than the simple one used earlier. This would look for the same login: prompt, however, if one was not received, a single return sequence is sent and then it will look for login: again. Should line noise obscure the first login prompt then sending the empty line will usually generate a login prompt again.

## COMMENTS
Comments can be embedded in the chat script. A comment is a line which starts with the # (hash) character in column 1. Such comment lines are just ignored by the chat program. If a '#' character is to be expected as the first character of the expect sequence, you should quote the expect string. If you want to wait for a prompt that starts with a # (hash) character, you would have to write something like this:

\# Now wait for the prompt and send logout string

'# ' logout

## SENDING DATA FROM A FILE
If the string to send starts with an at sign (@), the rest of the string is taken to be the name of a file to read to get the string to send. If the last character of the data read is a newline, it is removed. The file can be a named pipe (or fifo) instead of a regular file. This provides a way for chat to communicate with another program, for example, a program to prompt the user and receive a password typed in.

## ABORT STRINGS
Many modems will report the status of the call as a string. These strings may be CONNECTED or NO CARRIER or BUSY. It is often desirable to terminate the script should the modem fail to connect to the remote. The difficulty is that a script would not know exactly which modem string it may receive. On one attempt, it may receive BUSY while the next time it may receive NO CARRIER.

These "abort" strings may be specified in the script using the ABORT sequence. It is written in the script as in the following example:

ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT

This sequence will expect nothing; and then send the string ATZ. The expected response to this is the string OK. When it receives OK, the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received the remainder of the script is executed. However, should the modem find a busy telephone, it will send the string BUSY. This will cause the string to match the abort character sequence. The script will then fail because it found a match to the abort string. If it received the string NO CARRIER, it will abort for the same reason. Either string may be received. Either string will terminate the chat script.

## CLR_ABORT STRINGS
This sequence allows for clearing previously set ABORT strings. ABORT strings are kept in an array of a pre-determined size (at compilation time); CLR_ABORT will reclaim the space for cleared entries so that new strings can use that space.

## SAY STRINGS
The SAY directive allows the script to send strings to the user at the terminal via standard error. If chat is being run by pppd, and pppd is running as a daemon (detached from its controlling terminal), standard error will normally be redirected to the file /var/log/ppp/connect-errors.

SAY strings must be enclosed in single or double quotes. If carriage return and line feed are needed in the string to be output, you must explicitly add them to your string.

The SAY strings could be used to give progress messages in sections of the script where you want to have 'ECHO OFF' but still let the user know what is happening. An example is:

ABORT BUSY

ECHO OFF

SAY "Dialling your ISP...\n"

'' ATDT5551212

TIMEOUT 120

SAY "Waiting up to 2 minutes for connection ... "

CONNECT ''

SAY "Connected, now logging in ...\n"

ogin: account

ssword: pass

$ \c

SAY "Logged in OK ...\n" etc ...

This sequence will only present the SAY strings to the user and all the details of the script will remain hidden. For example, if the above script works, the user will see:

Dialling your ISP...

Waiting up to 2 minutes for connection ... Connected, now logging in ...

Logged in OK ...

## REPORT STRINGS
A report string is similar to the ABORT string. The difference is that the strings, and all characters to the next control character such as a carriage return, are written to the report file.

The report strings may be used to isolate the transmission rate of the modem's connect string and return the value to the chat user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the expect string. The use of the same string for a report and abort sequence is probably not very useful, however, it is possible.

The report strings to no change the completion code of the program.

These "report" strings may be specified in the script using the REPORT sequence. It is written in the script as in the following example:

REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account

This sequence will expect nothing; and then send the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received the remainder of the script is executed. In addition the program will write to the expect-file the string "CONNECT" plus any characters which follow it such as the connection rate.

## CLR_REPORT STRINGS
This sequence allows for clearing previously set REPORT strings. REPORT strings are kept in an array of a pre-determined size (at compilation time); CLR_REPORT will reclaim the space for cleared entries so that new strings can use that space.

## ECHO
The echo options controls whether the output from the modem is echoed to stderr. This option may be set with the -e option, but it can also be controlled by the ECHO keyword. The "expect-send" pair ECHO ON enables echoing, and ECHO OFF disables it. With this keyword you can select which parts of the conversation should be visible. For instance, with the following script:

ABORT 'BUSY'

ABORT 'NO CARRIER'

'' ATZ

OK\r\n ATD1234567

\r\n \c

ECHO ON

CONNECT \c

ogin: account

all output resulting from modem configuration and dialing is not visible, but starting with the CONNECT (or BUSY) message, everything will be echoed.

## HANGUP
The HANGUP options control whether a modem hangup should be considered as an error or not. This option is useful in scripts for dialling systems which will hang up and call your system back. The HANGUP options can be ON or OFF.

When HANGUP is set OFF and the modem hangs up (e.g., after the first stage of logging in to a callback system), chat will continue running the script (e.g., waiting for the incoming call and second stage login prompt). As soon as the incoming call is connected, you should use the HANGUP ON directive to reinstall normal hang up signal behavior. Here is an (simple) example script:

ABORT 'BUSY'

'' ATZ

OK\r\n ATD1234567

\r\n \c

CONNECT \c

'Callback login:' call_back_ID

HANGUP OFF

ABORT "Bad Login"

'Callback Password:' Call_back_password

TIMEOUT 120

CONNECT \c

HANGUP ON

ABORT "NO CARRIER"

ogin:--BREAK--ogin: real_account

etc ...

## TIMEOUT
The initial timeout value is 45 seconds. This may be changed using the -t parameter.

To change the timeout value for the next expect string, the following example may be used:

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2

This will change the timeout to 10 seconds when it expects the login: prompt. The timeout is then changed to 5 seconds when it looks for the password prompt.

The timeout, once changed, remains in effect until it is changed again.

## SENDING EOT
The special reply string of EOT indicates that the chat program should send an EOT character to the remote. This is normally the End-of-file character sequence. A return character is not sent following the EOT. The EOT sequence may be embedded into the send string using the sequence ^D.

## GENERATING BREAK
The special reply string of BREAK will cause a break condition to be sent. The break is a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. It may be used to cycle through the available transmission rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded into the send string using the \K sequence.

## ESCAPE SEQUENCES
The expect and reply strings may contain escape sequences. All of the sequences are legal in the reply string. Many are legal in the expect. Those which are not valid in the expect sequence are so indicated.

''

Expects or sends a null string. If you send a null string then it will still send the return character. This sequence may either be a pair of apostrophe or quote characters.

\b

represents a backspace character.

\c

Suppresses the newline at the end of the reply string. This is the only method to send a string without a trailing return character. It must be at the end of the send string. For example, the sequence hello\c will simply send the characters h, e, l, l, o. (not valid in expect.)

\d

Delay for one second. The program uses sleep(1) which will delay to a maximum of one second. (not valid in expect.)

\K

Insert a BREAK (not valid in expect.)

\n

Send a newline or linefeed character.

\N

Send a null character. The same sequence may be represented by \0. (not valid in expect.)

\p

Pause for a fraction of a second. The delay is 1/10th of a second. (not valid in expect.)

\q

Suppress writing the string to the SYSLOG file. The string ?????? is written to the log in its place. (not valid in expect.)

\r

Send or expect a carriage return.

\s

Represents a space character in the string. This may be used when it is not desirable to quote the strings which contains spaces. The sequence 'HI TIM' and HI\sTIM are the same.

\t

Send or expect a tab character.

\T

Send the phone number string as specified with the -T option (not valid in expect.)

\U

Send the phone number 2 string as specified with the -U option (not valid in expect.)

\\

Send or expect a backslash character.

\ddd

Collapse the octal digits (ddd) into a single ASCII character and send that character. (some characters are not valid in expect.)

^C

Substitute the sequence with the control character represented by C. For example, the character DC1 (17) is shown as ^Q. (some characters are not valid in expect.)

## ENVIRONMENT VARIABLES
Environment variables are available within chat scripts, if the -E option was specified in the command line. The metacharacter $ is used to introduce the name of the environment variable to substitute. If the substitution fails, because the requested environment variable is not set, nothing is replaced for the variable.

## TERMINATION CODES
The chat program will terminate with the following completion codes.

0

The normal termination of the program. This indicates that the script was executed without error to the normal conclusion.

1

One or more of the parameters are invalid or an expect string was too large for the internal buffers. This indicates that the program as not properly executed.

2

An error occurred during the execution of the program. This may be due to a read or write operation failing for some reason or chat receiving a signal such as SIGINT.

3

A timeout event occurred when there was an expect string without having a "-subsend" string. This may mean that you did not program the script correctly for the condition or that some unexpected event has occurred and the expected string could not be found.

4

The first string marked as an ABORT condition occurred.

5

The second string marked as an ABORT condition occurred.

6

The third string marked as an ABORT condition occurred.

7

The fourth string marked as an ABORT condition occurred.

...

The other termination codes are also strings marked as an ABORT condition.

Using the termination code, it is possible to determine which event terminated the script. It is possible to decide if the string "BUSY" was received from the modem as opposed to "NO DIAL TONE". While the first event may be retried, the second will probably have little chance of succeeding during a retry.

## SEE ALSO
Additional information about chat scripts may be found with UUCP documentation. The chat script was taken from the ideas proposed by the scripts used by the uucico program.

uucico(1), uucp(1)

## COPYRIGHT
The chat program is in public domain. This is not the GNU public license. If it breaks then you get to keep both pieces.