+ pafc - service discovery client
+
pafc [-i client_id] [-p version] addr
+pafc [-i client_id] [-p version] [-n server-index>] domain
+pafc [-a] domain
+pafc -l
+pafc -h
pafc is an interactive Pathfinder service discovery client, primarily +intended for test and debugging purposes.
+ +pafc accept a single argument, which is either a Pathfinder service +discovery domain name, or an address to a server. The argument will +first be treated as a domain name, and then, if no such service +discovery domain can be found, as a server address in XCM format.
+ +pafc looks up domain files in the same manner as a libpaf-based client +would. See the libpaf documentation for details on the format and +location of such domain files.
+ +If the service discovery domain name resolves to multiple addresses +(i.e., the file contains multiple server addresses), the first server +in the list will be used.
+ +-i <client_id>
+Specify the client identifier to be used, in hexadecimal format. If
+not set, pafc uses a randomly generated id.-p <version>
+Specify the protocol version to be advertised to the server.-n <server-index>
+Connect to server address at server-index in the list of servers
+for the specified domain. Default is 0.-a
+List all server addresses of specified domain.-l
+List all configured domains (i.e., files in the domains directory).-h
+Display pafc usage information.If a connection to a Pathfinder server was successfully established, +pafc will present the user with a prompt.
+ +pafc supports the following interactive commands:
+ +hello
+Send a Pathfinder protocol hello request, and output the result
+of the response (i.e., the result and the protocol version used).
+An interactive hello will always the second protocol-level hello
+command, since pafc automatically performs the initial handshake
+at transport-level connection establishment.id
+Print the session's client id. This interactive command requires
+no protocol-level interaction with the server.ping
+Send a Pathfinder protocol ping request, and output the result,
+including the latency.clients
+List all clients connected to the server, including the pafc
+session itself.services
+List all services currently published on the server, including
+orphan services (i.e., services for which there is currently
+no owner), by all clients.subscriptions
+List all subscriptions issued to the server, by all clients.publish [<service-id>] <generation> <ttl> [<prop-name> <prop-value>] ...
+Publish a new service, or republish an update service.
The service identifier is optional. If left out, pafc will generate +a random service id for the published service.
+ +In case prop-value is an integer in decimal format, it will +be added as an integer. Otherwise, the string property value type +will be used. To force the use of strings, use '|integer|' +(e.g. |4711|).
+unpublish <service-id>
+Unpublish a service. The server only allows services published by
+the same user as the pafc session belongs to be unpublished.subscribe [<filter-expression>]
+Subscribe to changes in services, with an optional filter expression.
The LDAP search filter-like filter language is described in the +Pathfinder protocol specification.
+ +If the filter is left out, pafc will receive notifications for +changes to any service.
+unsubscribe <subscription-id>
+Unsubscribe a service. The server only allows the removal of
+subscriptions issued by this pafc session.help [<cmd>]
+Display a list of command, or in case the optional argument is
+supplied, information on a specific command.quit
+Terminate the Pathfinder protocol connection and quit pafc. Any
+services publish as a part of this pafc session will be left as
+orphans on the server.Most of the pafc interactive commands maps closely to a Pathfinder +protocol-level command. For more information on command requests and +responses, please refer to the appropriate section of the Pathfinder +protocol specification.
+ +In the below session, a user connects to a server serving the service +discovery domain "oam" and checks the latency:
+ +$ pafc oam
+> ping
+0.4 ms
+OK.
+>
+The below is pafc session where the user connects to a server on the +host 192.168.1.59, serving a service discovery on a TLS server socket +bound to port 4711. The user checks pafc's client id, list all +clients, issues a subscription, and list all subscriptions. Another +client adds a matching service, and then modifies the same service. +The user then goes on to list all services.
+ +$ pafc tls:192.168.1.42:4711
+> id
+Client Id: 0x13b908adda6688d6
+> clients
+Client Id Remote Address Session Uptime
+13b908adda6688d6 tls:192.168.1.59:58700 0:00:02
+4e9a2e1d7ab98fcc tls:192.168.1.59:58692 0:00:04
+OK.
+> subscribe (name=service-a)
+Subscription Id 5f2928fd0233f5c1.
+OK.
+> subscriptions
+Subscription Id Owner Id Filter Expression
+1cda481d5018aaeb 4e9a2e1d7ab98fcc -
+5f2928fd0233f5c1 13b908adda6688d6 (name=service-a)
+OK.
+> Subscription 5f2928fd0233f5c1: Match type: appeared; Service id: 616fcc6f1bf6aabe; Generation: 0; TTL: 60; Client Id: 0x4e9a2e1d7ab98fcc; Properties: {'name': 'service-a', 'address': 'https://1.2.3.4:5555'}
+Subscription 5f2928fd0233f5c1: Match type: modified; Service id: 616fcc6f1bf6aabe; Generation: 1; TTL: 60; Client Id: 0x4e9a2e1d7ab98fcc; Properties: {'name': 'service-a', 'address': 'https://1.2.3.4:5678'}
+>
+> services
+ Service Id Gen TTL Orphan Tmo Owner Properties
+616fcc6f1bf6aabe 1 60 - 4e9a2e1d7ab98fcc {'name': 'service-a', 'address': 'https://1.2.3.4:5678'}
+OK.
+>
+In this session, a pafc user connects to a server by address, and +publishes a service, and then modifies that service:
+ +$ pafc tls:192.168.1.42:4711
+> publish 0 60 name service-a address https://1.2.3.4:5555
+Service Id 616fcc6f1bf6aabe.
+OK.
+> publish 616fcc6f1bf6aabe 1 60 name service-a address https://1.2.3.4:5678
+OK.
+>
+Pathfinder is Copyright (c) 2020, Ericsson AB, and released under +the BSD 3-Clause Revised License.
+ +pafd(8).
+ +
+ pafd - service discovery server
+
pafd [options...] [domain-addr...]
pafd is a server for use in a Pathfinder light-weight service +discovery system.
+ +pafd is designed to be used as a daemon (i.e., a UNIX server process), +but does not daemonize itself (e.g., it does not call fork() and runs +in the background).
+ +pafd may be supplied zero or more arguments. Each such argument must a +server socket address, in XCM format.
+ +For each address, the server will instantiate a service discovery +domain, and bind to the socket. Thus, a server process may be used to +serve more than one service discovery domain.
+ +pafd may be configured to serve same service discovery domain on
+different server sockets simultaneously, using the -m option.
In case domains are specified both in the configuration file, and as +arguments or options, all domains in the configuration file will be +ignored, and only the domains specified on the command-line will be +used.
+ +-m
+Instantiate a multi-socket service discovery domain. Each server
+socket address is separated by '+' (which may not be used in the
+address).
-s
+Enable logging to console (standard error). Console logging is
+disabled by default.
-o <file>
+Enable logging directly to file.
-b <backup-count>
+Enable log rotation for direct file logging, and keep backup-count
+number of copies.
-x <log-file-max-size>
+Set the maximum log file size (in bytes) before a file is rolled
+over. Only has effect in case direct file logging with log rotation
+is enabled. Default is 1000000.
-n
+Disable logging to syslog. Syslog logging is enabled by default.
-y <facility>
+Set syslog facility to use.
-l <level>
+Discard log messages with a severity level below level.
-c <max-clients>
+Set the maximum number of allowed connected clients to
+max-clients. The default is no limit.
-f <conf-file>
+Read configuration from conf-file.
-v
+Display pafd version information.
-h
+Display pafd usage information.
Options override any configuration set by a configuration file.
+ +The below example spawns one server process with two service discovery +domains; one on a UNIX domain socket "foo", and one answering on TCP +port 4711:
+ +$ pafd ux:foo tcp:*:4711
+This example spawns a server process, instantiates one domain, and +enables console logging and disables syslog and log filtering:
+ +$ pafd -n -s -l debug ux:foo
+INFO:root:Server version 1.0.3 started with configuration: domains: [ ['ux:foo'] ], log: { console: true, syslog: false, filter: debug, facility: daemon }
+pafd may be configured to impose limits on various types of +server-side resources. Such limits may be put in place to protect the +server from CPU overload and memory or other resource exhaustion, and +to mitigate damage caused by malicious or otherwise misbehaving +clients.
+ +There are three types of resources; clients, services and +subscriptions.
+ +The total resource limits specifies the maximum number of objects that +may be instantiated, of a particular resource type, on the level of a +service discovery domain.
+ +The user resource limits specifies per-user limits, within a +particular service discovery domain. All users have the same limits +with same upper bound values. The user is accounted against the number +of objects used in that domain, for all clients associated with that +user.
+ +pafd relies on transport protocol level user authentication. For TLS, +the X.509 subject key id (SKI) is used to identify a user. For TCP, +the client's source IP address serves the same role. Clients +connecting using other transport protocols or IPC mechanisms (i.e., +UNIX domain sockets) all qualifies as the same user.
+ +Each client uses a number of service-side file descriptors (usually +one or two), depending on XCM transport used. For large servers, the +per-process file descriptor limit (see RLIMIT_NOFILE in setrlimit(2)) +or the global limit (fs.file-max) may need to be increased.
+ +The configuration file uses YAML as its base format. The root is a +YAML dictionary (also known as a YAML mapping, or hash), with three +keys, all optional; domains, resources, and log.
+ +domains, if present, must be a list of service discovery domain +dictionaries. A domain dictionary must either have a key sockets, +which value is a list of all sockets (or endpoints) that should be +bound to that domain. addrs may be used as an alternative name.
+ +A domain may also optionally be given a name, stored as a string under +the name key. This domain name is only used for logging and +documentation and is not seen in the by clients to the Pathfinder +server.
+ +Each element of the sockets list is a socket. A socket is either the +address in the form of a string (in XCM format), or a dictionary, +where the address must be the value of the key addr.
+ +For TLS addresses, an addition key tls may be present in the socket +dictionary. tls, if present, must be a dictionary with zero or more +of four possible entries. cert, key, tc may be used to override +the default XCM certificate, private key, or trusted CA bundle file +locations. The key crl may be included in case certificate +revocation list checking is to be employed. The value of each such key +must be a filename in string format.
+ +resources, if present, must be a dictionary, containing either or +both of two keys total and user.
+ +The value of total must be a dictionary with any/all of the +following keys: clients, services, and/or subscriptions. The +values must all be integers, and represent the upper bound for the +number of instances of a particular resource type, for a service +discovery domain.
+ +The value of user is a dictionary in the same format as total's.
+ +log, if present, must be a dictionary, and may contain any of the +following keys: console (with a boolean value), syslog (boolean), +facility (string), and filter (string). See the corresponding +command-line options for details.
+ +Configuration file example:
+ +domains:
+- addrs: # Domain which may be access via two server sockets
+ - tls:*:4711
+ - ux:local
+- addrs: # Second domain, only available at one socket
+ - tls:192.168.1.59:5711
+
+resources:
+ total: # Per-domain limits
+ clients: 10000
+ services: 10000
+ subscriptions: 10000
+ user: # Limits per "user" (e.g., TLS certificate)
+ clients: 1000
+ services: 1000
+ subscriptions: 1000
+
+log:
+ console: true
+ syslog: true # Usually disabled in containized environments
+ facility: daemon
+ filter: info
+Pathfinder is Copyright (c) 2020, Ericsson AB, and released under +the BSD 3-Clause Revised License.
+ +pafc(1).
+ +