gws.conf

NAME
DESCRIPTION
AUTHORS
SEE ALSO

NAME

gws.conf − Gigapxy web service daemon configuration file.

DESCRIPTION

gws(1) is the gigapxy(1) web service daemon, responsible for processing incoming requests. The configuration file contains the parameters read by the daemon at launch. The config file is human−readable and is in libconfig format. An example of a gws.conf is provided with the installation; please refer to it or the libconfig manual.

Once the parameters are read by gws, the daemon operates with those values util the configuration is re−loaded in response to SIGHUP.

All gws(1) settings beginning with the ws. prefix, as in ws.section.param. A configuration file could contain other (non-gws) settings too; gws will simply disregard those.

The configuration settings are given below. The default value for a setting is given in square brackets as [default]. Parameters without default values are mandatory.

ws.ng.socket_path = path [/var/run/gpx-ngcomm.socket]
is the domain socket path for communications between gws and the attached gng’s.

ws.ng.force_shutdown = true | false [true]
If true, gws will attempt to shut down (kill −SIGTERM) all attached ng’s on shutdown.

ws.ng.pick_method = method [round-robin]
gng selection method, using one of the following criteria: round-robin - next engine from the (circular) list; min-channels - engine with the minimum channels; min-clients - engine with the minimum clients.

ws.ng.accept_min_attached = num [1]
The number of NGs that should be attached to this gws before it can accept user requests.

ws.split_channels = true | false [false]
When set to true, gws chooses a gng for every new client before anything else, using ws.ng.pick_method. This allows to load-balance a single channel to multiple gng-s/cores. The default method (with this setting off) matches one channel to a particular gng: all clients for that channel get handled by the initially-assigned gng.

ws.log.*
Below are the settings pertaining to different modules within gws(1). Setting verbosity for one of those allows to variate debug log detailization for specific modules within the program. Not every module though has a specific level attributed to it; most default to the non-specific common level.

The follow settings are for the application (debug) log. Application log captures various actions as they happen without any specific focus.

ws.log.level_default = err| crit| warn| norm| info| debug [info]
Defines the level of verbosity for the log across all modules.

ws.log.level_common = err| crit| warn| norm| info| debug [info]
Sets the level of verbosity for non-specific modules. NB: setting this level to debug will result in a VERY verbose output.

ws.log.level_syscall = err| crit| warn| norm| info| debug [info]
Sets the level of verbosity for system call and libc wrappers.

ws.log.level_bufd = err| crit| warn| norm| info| debug [info]
Sets the level of verbosity for (stream) buffer management operations.

ws.log.level_tput = err| crit| warn| norm| info| debug [info]
Sets the level of verbosity for operations on throughput statistics.

ws.log.file = path
Full path to debug log.

ws.log.max_size_mb = num [16]
Maximum file size (in Mb, i.e. 1048576−byte chunks). Log is rotated when this size is exceeded. gws will force−rotate its current log in response to SIGUSR1.

ws.log.max_files = num [16]
Maximum number of files to rotate to. The next rotation after this limit removes the oldest rotated log.

ws.log.time_format = local| gmt| raw| raw_mono| no_time| [local]
Sets format to display timestamps for log entries. local will loglocal−timezone specific time in YYYY-MM-DD HH24:MI TZ format. gmt will log GMT time in the same human−readable format as local; raw logs high−resolution time as the number of seconds.nanoseconds since the Epoch (1970-01-01 00:00:00 UTC); raw−mono logs system−specific monotonic time (used for timespan measurement, not correlated to clock time). no_time logs no time at all.

ws.log.show_pid = true|false [true]
Display PID as a log entry field.

ws.log.enable_syslog = true|false [true]
Write errors, warnings and critical messages to syslog(2).

ws.access_log.*
The following settings are for gws access log, serving a specific purpose of capturing channel and client session statistics. Access log is updated every time a new data stream is opened or closed. The entry types are:

OPEN_CHANNEL channel_address
gws
opens a connection to the given channel. Data starts flowing from the channel (specified by channel_address) into internal storage and on to channel subscribers.

CLOSE_CHANNEL channel_address num_users
gws
closes a connection to the given channel (specified by channel_address). num_users were subscribed to the channel at the point of closure.

OPEN_CLIENT client_address channel_address
A client at client_address successfully subscribes to channel at channel_address. This is prior to the moment when the first chunk of data gets sent to the client (by designated gng).

CLOSE_CLIENT client_address channel_address num_users uptime nbytes npkts
Client session ends; summary statistics showing: number of subscribers num_users left for the given channel; session uptime shown as seconds.nanoseconds; total bytes (nbytes) transferred; total packets/chunks (npkts) transferred.

NG_ATTACH/DETACH/QUIT pid index fd
New gng(1) attached/detached/quit to/from gws(1). Shown are: gng pid, internal index and connection fd. NG_QUIT means that gng may have sent no CLOSE_xx messages prior to its exit.

AUTH_START/EXIT pid
Authorization helper started/exited. Shown is the helper’s pid.

ws.access_log.file = path
Full path to access log.

ws.channel_groups = path []
Full path to aliased channel-group configuration file (if any). If empty, no channel groups will be defined. See details on aliased channel groups in channels.conf(5)

ws.channel_group_refresh = um [0]
Check every N seconds if channel-group config file changed, re-load and apply new channel-group settings if it did.

ws.access_log.max_size_mb = num [16]
Maximum file size (in Mb, i.e. 1048576−byte chunks). Access log is rotated when this size is exceeded.

ws.access_log.max_files = num [16]
Maximum number of files to rotate to. The next rotation after this limit removes the oldest rotated access log.

ws.access_log.time_format = local| gmt| raw| raw_mono| no_time| [local]
Sets format to display timestamps for log entries. See ws.log.time_format for details.

ws.access_log.show_pid = true|false [true]
Display PID as a log entry field.

ws.listener.*
The following are the settings equally applying to listeners of the two types of requests (admin and user) handled by the application. You can define up to 32 user and 4 admin listeners. See gigapxy−commented.conf for an example of multiple−listener config.

ws.listener.*.alias = unique-alias [{ifc}:{port}]
Unique human-readable identifier for the given listener. Populated by default by interface name and port (see below) separated by colon. For ifc=eth0 and port=3030, the alias, unless specified otherwise, would be set to eth0:3030.

ws.listener.*.ifc = interface [any]
Name or the address of the network interface for the listener of requests. any, all signifies the ’anonymous’ interface with the address of 0, which means that the first eligible network interface will be picked by your OS.

ws.listener.*.port = number
Port number for the listener.

ws.listener.*.default_af = inet | inet6 [inet]
is the address family to be used when an interface cannot be uniquely linked to a family. For instance, an interface could have both IPv4 and IPv6 addresses associated with it.

ws.listener.*.is_safe = true|false [false]
Perform no authorization checks on user requests from this listener (allow all).

ws.pidfile.directory = dirname [/var/run/gigapxy]
Directory for the pidfile (must be writable by ws.run_as_user).

ws.pidfile.name = filename [gws−{user_port}.pid]
Name (w/o directory part of the path) of the pidfile, the default value uses the user−request listener port number.

ws.idle_clk_ms = milliseconds [−1]
Time (ms) to wait before doing any idle-time tasks, −1 = no limit. This sets the resolution (or granularity) for the timeouts or any other tasks done in idle time. The default value will have it perform idle tasks only when an actual event (connection, signal, etc.) interrupts the wait loop.

ws.max_sockets_to_accept = num [127]
Max number of sockets to accept in one event. When an incoming connection breaks the event loop, the module will try to accept(2) up to this limit of new sockets.

ws.multicast_ifc = name [any]
Default interface to use for sourcing multicast data.

ws.rcv_low_watermark = num [16]
Do not trigger a socket READ event unless at least num bytes have been received.

ws.run_as_user = username []
Run as this user when running as a daemon (if empty, do not switch).

ws.run_as_uid = uid [−1]
Run as the given user (uid) when running as a daemon (if −1, do not switch). If gid is not specified, then gid = uid. uid > 0 will override run_as_user.

ws.run_as_gid = gid [−1]
Run in the given group (gid) when running as a daemon (if −1, gid = uid).

ws.tcp_no_delay = true | false [true]
Set TCP_NODELAY option for each accepted socket.

ws.use_http10_get = true | false [false]
Use HTTP/1.0 in channel (GET) requests for data. This is to prohibit the server to use chunked transfer encoding in response. nginx, often used as a proxy layer, has chunked encoding enabled by default and may send video stream wrapped as HTTP chunks. For now, gigapxy does NOT support parsing HTTP chunks in video streams.

ws.user_ping = true | false [false]
Allow ’ping’ or ’status’ requests on user−request listeners. NB: this feature is provided solely to maintain compatibility with udpxy which has no dedicated admin listeners. User−side pings are disabled by default, DO NOT ENABLE unless absolutely necessary, it is considered a safer practice to use admin listeners for all admin requests.

ws.legacy_multicast_api = true | false [false]
Use older (family-specific) API to manage multicast subscriptions.

ws.non_daemon = true | false [false]
If started as root, become a daemon if true.

ws.enforce_core_dumps = true | false [false]
When set to true, the process invokes the necessary syscalls to make itself core-dumpable and set core limit to unlimited. The default value of false leaves it to the shell defaults. NB: Under certain Linux versions, UID−changing daemons become non−core−dumpable (see /proc/sys/fs/suid_dumpable and prctl(2) for details).

ws.quiet = true | false [false]
No output to stdout/stderr if true.

ws.process_limits.*
This section allows to impose limits on the running process via setrlimit(2) syscall. Memory limits are specified as strings containing numerals and an optional denominator suffix, such as Kb, Mb or Gb. The number can have a fraction, so "1.5Kb" evaluates to 1024 + 512 = 1536 − the value to be submitted as a limit. "0" value or omission of a limit parameter leaves current (system−imposed) limit unchanged.

ws.process_limits.rss = {N}{suffix} ["0"]
Resident memory cap: a process cannot exceed this amount in resident memory, memory allocation call(s) should fail. NB: This limit cannot be enforced under Linux, where it would be replaced by RLIMIT_AS (virtual memory cap). If both RSS and VMEM are to be limited under Linux, the smaller value is used with RLIMIT_AS. Under FreeBSD, RSS limit is fully supported.

ws.process_limits.vmem = {N}{suffix} ["0"]
Virtual memory cap = RLIMIT_AS. Used in place of RSS cap under Linux. Both Linux and FreeBSD fully support it.

ws.http_read_timeout_ms = milliseconds [200]
Timeout (in milliseconds) to read an HTTP−message portion.

ws.user_request_timeout_ms = milliseconds [500]
Timeout (in milliseconds) for a user request to be processed.

ws.admin_request_timeout_ms = milliseconds [300]
Timeout (in milliseconds) for an admin request to be processed.

ws.module_request_timeout_ms = milliseconds [100]
Timeout (in milliseconds) for a module request to be processed. Module requests are those that go between gws and gng.

ws.http_data_content_type = type_specifier [application/octet-stream]
HTTP Content-Type for data payload.

ws.channel_sample_timeout_ms = milliseconds [−1]
Pre-sample each new channel trying to read from it with the given timeout; unless −1 == timeout, then do NOT pre-sample channels. NB: channels will be pre-sampled by gws, which will therefore wait and suffer the associated latency penalty.

USE WITH DISCRETION.

ws.tput_stats.*
The following section specifies the parameters needed for engines to report traffic throughput statistics, queried using report admin request. See gigapxy(1) for details on reports and admin request particulars.

ws.tput_stats.enabled = true | false [true]
Do not provide channel/client statistics unless true. Please note that engines will use additional CPU cycles to gather and calculate relevant statistics.

ws.tput_stats.channel_path = posix_shmem_path [/gxy-cha.shm]
POSIX shared memory path for channel statistics (<= 32 characters).

ws.tput_stats.client_path = posix_shmem_path [/gxy-cli.shm]
POSIX shared memory path for client statistics (<= 32 characters).

ws.tput_stats.max_channel_records = num [250]
Max number of records (across all engines) in channel statistics. This should be no less than the maximum number of channels to be handled at once.

ws.tput_stats.max_client_records = num [1000]
Max number of records (across all engines) in client statistics storage. This should be no less than the maximum number of clients to be handled at once by all engines.

ws.tput_stats.max_speed_delta = num [8]
Max difference (in Kb) between channel and client speeds. Speed delta is visible in TPS reports and will be highlighted if delta gets exceeded.

ws.report.*
The following section specifies the parameters needed to support generation of various reports.

ws.report.default.type = name [traffic]
Default report type to use (with a URL not specifying one).

ws.report.default.format = name [html]
Default report format to use (with a URL not specifying one).

ws.report.memory.min = bytes [524288]
Initial memory for the spool buffer (to contain full report text prior to the output).

ws.report.memory.max = bytes [16777216]
Maximum memory for the spool buffer (to contain full report text prior to the output).

ws.report.max_send_attempts = num [16]
Max number of transfer/send/output attempts to take if cannot output all at once.

ws.report.cache_timeout_ms = num [500]
Reports will be cached and served to subsequent requests within this timespan (ms), or NOT cached at all if the value <= 0 (a fresh report will be generated for each request).

ws.report.backup_file = filepath []
File to save each report into (overwriting the previous one). If empty, do NOT save.

ws.sync.regular_timeout_ms = ms [500]
After a GNG attaches, synchronize (retrieve) channel/client stats from TPS cache in N ms after the attach. Enabled only if TPS (ws.tput_stats.enabled is true).

ws.sync.forced_timeout_ms = ms [10000]
If at least one GNG is attached, synchronize (retrieve) channel/client stats from TPS cache every N ms. Enabled only if TPS (ws.tput_stats.enabled is true).

ws.redirect.err_channel = channel_URL []
Redirect client (via HTTP 302) to channel_address if requested channel is unavailable (for any reason other than an error in an internal component of gigapxy). Channel URL must be a full HTTP URL that will be returned to client via HTTP 302 response.

ws.redirect.no_access = channel_URL []
Redirect client (via HTTP 302) to channel_address if access to the requested channel has been denied (by an authorization helper). Channel URL must be a full HTTP URL that will be returned to client via HTTP 302 response.

ws.psensors.*
Performance sensors allow to measure resource utilization between two specific points within the application, using the metrics provided by utime(2) utime(2) call at each end of the sensor. All sensor data will be printed out at the application exit in the format similar to the output of time(1) utility.

Performance sensors are a debugging/profiling facility and incur additional load on the system.

USE WITH DISCRETION.

Defined sensors:
app
= application runtime; ev_loop = event processing (all events); ev_read = reading/processing inbound data; ev_write = writing/processing outbound data; ev_err = processing error events; ev_pp = post−processing events; ws_userq = processing user requests; ws_admrq = processing administrative requests (reports, etc.).

ws.psensors.enable_all = true|false [false]
Enables all sensors if true, disables all otherwise. This is to initialize the set of enabled−sensor flags to either all ones (if enabled) or all zeros. This setting is to be used in combination with ws.psensors.except.

ws.psensors.except = sensor_list []
Enables sensors in the list if ws.psensors.enable_all is true, or disables those sensors if false. This way enable_all is used to initialize the set of sensors while except narrows it down by enabling/disabling its specific elements.

EXAMPLE A:

ws.psensors.enable_all = true; # Enable all sensors.

ws.psensors.except = ["ev_read", "ev_write"]; # Disable those listed herein.

Enables all sensors except ev_read and ev_write.

EXAMPLE B:

ws.psensors.enable_all = false; # Disable all sensors.

ws.psensors.except = ["ev_read", "ev_write"]; # Enable those listed herein.

Enables ev_read and ev_write sensors, all others are disabled.

ws.auth.*
Authorization helpers are user-defined applications (plug−ins) used by gws to screen user requests, based on request−specific data, such as user address, request URI, etc. gws starts one or several helpers and communicates with them via pipes connected to helpers’ STDIN and STDOUT streams. Example helper scripts (a1p-auth.sh, b2p-auth.sh) for two supported protocols are provided in /usr/share/gigapxy/scrpts under Linux (/usr/local/share/.. under FreeBSD).

ws.auth.enabled = true|false [false]
Enable helpers unless false.

ws.auth.helper_protocol = "A1P"|"B2P" ["A1P"]
Defines the communication protocol between gws and auth helpers. A1P is the older/simpler protocol, please see details in gigapxy.auth(5)

ws.auth.b_fields = fields ["USDP"]
This B2P-specific setting defines the fields (and their order) to be sent to auth helpers for evaluation. "USDP" stands for URL, Source, Destination and Peer - they will be sent to helpers in that order. Full list of protocol-supported fields can be found in gigapxy.auth(5)

ws.auth.exec = exec_path_with_params []
Specify full path to the helper executable with all command−line parameters. This constitutes a complete absolute−path to the helper binary with all required command−line options and parameters. NB: all helpers will be launched under user/group specified in ws.run_as* settings.

ws.auth.min_helpers = count [1]
Number of helpers to start with and always keep running.

ws.auth.max_helpers = count [1]
Maximum number of helpers to run.

ws.auth.deny_no_auth = true|false [false]
Deny access to URI/resource if authorization cannot be performed (due to an internal error). Allow by default so that authorization framework failure would not result in denial of service.

ws.auth.no_spawn_tmout = ms [5000]
Maximum time (ms) to disallow launching helpers after suspected cascading crashes. When a helper crashes shortly after being launched, gws disables further helper launches for the configured time period.

ws.auth.aux_params = list_of_params []
Additional A1P-specific parameters passed to auth helpers. The available parameters are:

listener-alias = alias for the originating listener

ws.auth.can_rewrite_endpoints = true|false [false]
Instructs gws using B2P protocol to be ready to re-write Source or Destination endpoints if specified in auth helper response message.

ws.auth.allow_custom_urls = true|false [false]
Instructs gws using B2P protocol to allow URLs that do not follow the two gigapxy-oriented patterns (udp/address:port or src/s_url/dst/d_url). This setting should be true if auth helpers were to match custom URLs to custom Source/Destination.

ws.auth.cache.*
Negative authentication responses can be cached by gws. This allows for much faster response when helpers’ time is at the premium and may better chances in case of a DOS attack. The cache’s eviction method is LRU (least recently used) and each entry (source URL) has a time-out.

ws.auth.cache.enabled = true|false [false]
Enable response cache if set to true.

ws.auth.cache.max_records = num [5000]
Set the maximum number of items in cache. If the number goes higher, extra items will be LRU−evicted.

ws.auth.cache.expiry_sec = num [300]
Set the lifespan of a cache item, in seconds.

AUTHORS

Pavel V. Cherenkov

SEE ALSO

gigapxy(1),gws(1),gng(1),gng.conf(5),channels.conf(5),gigapxy.auth(5)