- The libftrig interface takes care of all + The libftrig interface takes care of all the subtleties.
diff --git a/doc/ftrig.html b/doc/ftrig.html new file mode 100644 index 0000000..f4c4d6e --- /dev/null +++ b/doc/ftrig.html @@ -0,0 +1,184 @@ + + + + +
+s6
+Software
+skarnet.org
+
+libftrig is a portable Unix C programming interface allowing a +process (the subscriber or listener) to be instantly +notified when another process (the notifier or writer) +signals an event. +
+ + ++ Process A is notified of an event E when it gets a instant +notice that event E has happened; the notice may disrupt A's execution +flow. Notification is the opposite of polling, where A has to +periodically (every T milliseconds) check whether E happened and has no +other way to be informed of it. +
+ ++ Polling is generally considered bad practice - and is inferior to +notification in practically every case - for three reasons: +
+ ++ Notification, on the other hand, is generally optimal: reaction time is +zero, and resource consumption is minimal - a process can sleep as soon as +it's not handling an event, and only wake up when needed. +
+ ++ Of course, the problem of notification is that it's often more difficult +to implement. Notification frameworks are generally more complex, involving +lots of asynchronism; polling is widely used +because +it's easy. +
+ ++ Unix provides several frameworks so that a process B (or the kernel) can +notify process A. +
+ ++ We need a general framework to: +
+ ++ This requires a many-to-many approach that Unix does not provide natively, and +that is what libftrig does. +
+ + ++ Yes, a bus is a good many-to-many notification mechanism indeed. However, +a Unix bus can only be implemented via a daemon - you need a long-running +process, i.e. a service, to implement a bus. And s6 is a +supervision suite, i.e. a set of programs designed to manage +services; we would like to be able to use notifications in the supervision +suite, to be able to wait for a service to be up or down... without +relying on a particular service to be up. libftrig provides a notification +mechanism that does not need a bus service to be up, that's its +main advantage over a bus. +
+ ++ If you are not concerned with supervision and can depend on a bus service, +though, then yes, by all means, use a bus for your notification needs. +There is a skabus +project in the making, which aims to be simpler, smaller and more +maintainable than D-Bus. +
+ ++ libftrig is really a part of libs6: all the functions +are implemented in the libs6.a archive, or the libs6.so +dynamic shared object. However, the interfaces are different for notifiers +and listeners: +
+ + + + + diff --git a/doc/index.html b/doc/index.html index 1507705..9e3dde3 100644 --- a/doc/index.html +++ b/doc/index.html @@ -37,7 +37,8 @@ supervision that might help you understand the basics.git clone git://git.skarnet.org/s6
-s6
-Software
-skarnet.org
-
-
- Process A is notified of an event E when it gets a instant -notice that event E has happened; the notice may disrupt A's execution -flow. Notification is the opposite of polling, where A has to -periodically (every T milliseconds) check whether E happened and has no -other way to be informed of it. -
- -- Polling is generally considered bad practice - and is inferior to -notification in practically every case - for three reasons: -
- -- Notification, on the other hand, is generally optimal: reaction time is -zero, and resource consumption is minimal - a process can sleep as soon as -it's not handling an event, and only wake up when needed. -
- -- Of course, the problem of notification is that it's often more difficult -to implement. Notification frameworks are generally more complex, involving -lots of asynchronism; polling is widely used -because -it's easy. -
- -- Unix provides several frameworks so that a process B (or the kernel) can -notify process A. -
- -- We need a general framework to: -
- -- This requires a many-to-many approach that Unix does not provide natively, and -that is what libftrig does. -
- - -- Yes, a bus is a good many-to-many notification mechanism indeed. However, -a Unix bus can only be implemented via a daemon - you need a long-running -process, i.e. a service, to implement a bus. And s6 is a -supervision suite, i.e. a set of programs designed to manage -services; we would like to be able to use notifications in the supervision -suite, to be able to wait for a service to be up or down... without -relying on a particular service to be up. libftrig provides a notification -mechanism that does not need a bus service to be up, that's its -main advantage over a bus. -
- -- If you are not concerned with supervision and can depend on a bus service, -though, then yes, by all means, use a bus for your notification needs. -There is a skabus -project in the making, which aims to be simpler, smaller and more -maintainable than D-Bus. -
- -- libftrig is really a part of libs6: all the functions -are implemented in the libs6.a archive, or the libs6.so -dynamic shared object. However, the interfaces are different for notifiers -and listeners: -
- - - - - diff --git a/doc/libftrigr.html b/doc/libftrigr.html deleted file mode 100644 index 79c7694..0000000 --- a/doc/libftrigr.html +++ /dev/null @@ -1,283 +0,0 @@ - - - - -
-s6
-Software
-skarnet.org
-
- The ftrigr library provides an API for listeners, i.e. -programs that want to subscribe to fifodirs and be instantly -notified when the proper sequence of events happens. -
- -- Check the s6/ftrigr.h header for the -exact function prototypes. -
- -- Make sure your application is not disturbed by children it doesn't -know it has. This means paying some attention to the SIGCHLD handler, -if any, and to the way you perform waitpid()s. The best -practice is to use a -self-pipe -to handle SIGCHLD (as well as other signals the application needs to trap), -and to always use wait_nohang() to reap children, -simply ignoring pids you don't know. -
- -- If your (badly programmed) application has trouble handling unknown -children, consider using a ftrigrd service. -
- -- The src/pipe-tools/s6-ftrig-listen1.c and -src/supervision/s6-svwait.c files in the s6 package, -for instance, illustrate how to use the ftrigr library. -
- - --ftrigr_t a = FTRIGR_ZERO ; -tain_t deadline, stamp ; - -tain_now(&stamp) ; -tain_addsec(&deadline, &stamp, 2) - -// char const *path = FTRIGR_IPCPATH ; -// ftrigr_start(&a, path, &deadline, &stamp) ; -ftrigr_startf(&a, &deadline, &stamp) ; -- -
-ftrigr_start starts a session with a ftrigrd service listening on
-path.
-ftrigr_startf starts a session with a ftrigrd process as a child
-(which is the simplest usage).
-a is a ftrigr_t structure that must be declared in the stack and
-initialized to FTRIGR_ZERO.
-stamp must be an accurate enough timestamp.
-If the session initialization fails, the function returns 0 and errno is set;
-else the function returns 1.
-
-If the absolute time deadline is reached and the function -has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. - -Only local interprocess communications are involved; unless your system is -heavily overloaded, the function should return near-instantly. One or two -seconds of delay between stamp and deadline should be -enough: if the function takes more than that to return, then there is a -problem with the underlying processes. -
- -- You can have more than one session open in parallel, by declaring -several distinct ftrigr_t structures and calling -ftrigr_startf (or ftrigr_start) more than once. -However, this is useless, since one single session can handle -virtually as many concurrent fifodirs as your application needs. -
- --ftrigr_end(&a) ; -- -
-ftrigr_end frees all the resources used by the session. The -a structure is then reusable for another session. -
- --char const *path = "/var/lib/myservice/fifodir" ; -char const *re = "a.*b|c*d" ; -uint32 options = 0 ; - -uint16 id = ftrigr_subscribe (&a, path, re, options, &deadline, &stamp) ; -- -
-ftrigr_subscribe instructs the -s6-ftrigrd daemon, related to the open -session represented by the a structure, to subscribe to the -path fifodir, and to notify the application when it receives -a series of events that matches the re regexp. -options can be 0 or FTRIGR_REPEAT. If it is 0, the daemon will -automatically unsubscribe from path once re has been -matched by a series of events. If it is FTRIGR_REPEAT, it will remain -subscribed until told otherwise. -
- -- ftrigr_subscribe() returns 0 and sets errno in case of failure, or -a nonzero 16-bit number identifying the subscription in case of success. -
- --ftrigr_subscribe should return near-instantly, but if -deadline is reached, it will return 0 ETIMEDOUT. If -ftrigr_subscribe returns successfully, then the -s6-ftrigrd daemon is guaranteed to be listening on path, -and events can be sent without the risk of a race condition. -
- --uint16 list[1] ; -unsigned int n = 1 ; -char trigger ; -list[0] = id ; - -// r = ftrigr_wait_and(&a, list, n, &deadline) ; -r = ftrigr_wait_or(&a, list, n, &deadline, &trigger) ; -- -
- ftrigr_wait_and() waits for all the n fifodirs
-whose ids are listed in list to receive an event. It returns -1
-in case of error or timeout, or a non-negative integer in case of success.
- ftrigr_wait_or() waits for one of the n fifodirs
-whose ids are listed in list to receive an event. It returns -1
-in case of error or timeout; if it succeeds, the return value is the
-position in list, starting at 0, of the identifier that received
-an event; and trigger is set to the character that triggered that
-event, i.e. the last character of a sequence that matched the regular
-expression re used in the subscription.
-
- (from now on, the functions are listed with their prototypes instead -of usage examples.) -
- --int ftrigr_fd (ftrigr_t const *a) -- -
- Returns a file descriptor to select on for reading. Do not -read() it though. -
- --int ftrigr_update (ftrigr_t *a) -- -
- Call this function whenever the fd checks readability: it will -update a's internal structures with information from the -s6-ftrigrd daemon. It returns -1 if an error -occurs; in case of success, it returns the number of identifiers for -which something happened. -
- -- When ftrigr_update returns, -genalloc_s(uint16, &a->list) points to an array of -genalloc_len(uint16, &a->list) 16-bit unsigned -integers. Those integers are ids waiting to be passed to -ftrigr_check. -
- --int ftrigr_check (ftrigr_t *a, uint16 id, char *what) -- -
- Checks whether an event happened to id. Use after a -call to ftrigr_update(). -
- -
-s6
-Software
-skarnet.org
-
- The ftrigw library provides an API for notifiers, i.e. -programs that want to regularly announce what they're doing. -
- -- Notifiers should create a fifodir in a hardcoded place in the -filesystem, and document its location. Listeners will then be -able to subscribe to that fifodir, and receive the events. -
- -- Check the s6/ftrigw.h header for the -exact function prototypes. -
- --char const *path = "/var/lib/myservice/fifodir" ; -int gid = -1 ; -int forceperms = 0 ; -int r = ftrigw_fifodir_make(path, gid, forceperms) ; -- -
-ftrigw_fifodir_make creates a fifodir at the path location.
-It returns 0, and sets errno, if an error occurs.
-It returns 1 if it succeeds.
-If a fifodir, owned by the user, already exists at path, and
-forceperms is zero, then ftrigw_fifodir_make immediately
-returns a success. If forceperms is nonzero, then
-it tries to adjust path's permissions before returning.
-
-If gid is negative, then path is created "public". -Any listener will be able to subscribe to path. -If gid is nonnegative, then path is created "private". -Only processes belonging to group gid will be able to -subscribe to path. -
- --char event = 'a' ; -r = ftrigw_notify(path, event) ; -- -
-ftrigw_notify sends event to all the processes that are -currently subscribed to path. -It returns -1 if an error occurs, or the number of successfully notified -processes. -
- --When stray KILL signals hit s6-ftrigrd processes, -1. it's a sign of incorrect system administration, 2. they can leave -unused named pipes in the fifodir. It's the fifodir's owner's job, i.e. -the notifier's job, to periodically do some housecleaning and remove -those unused pipes. -
- --r = ftrigw_clean(path) ; -- -
-ftrigw_clean cleans path. It returns 0, and sets errno, -if it encounters an error. It returns 1 if it succeeds. -
- - - diff --git a/doc/libs6/accessrules.html b/doc/libs6/accessrules.html new file mode 100644 index 0000000..bd98b5f --- /dev/null +++ b/doc/libs6/accessrules.html @@ -0,0 +1,331 @@ + + + + +
+libs6
+s6
+Software
+skarnet.org
+
+ The following functions and structures are declared in the s6/accessrules.h header, +and implemented in the libs6.a or libs6.so library. +
+ ++ accessrules is an access control library. It looks up +a key in a user-specified database, then returns a code depending on +whether the database allows access (in which case additional information +can also be returned), denies access, or does not contain the key. +
+ ++ accessrules has been designed to be easily extensible to any +database format and any key format. +
+ ++ Check the s6/accessrules.h header for the exact definitions. +
+ ++ A s6_accessrules_backend_func_t is the type of a function +that takes a single key, looks it up in a database, and returns the result. +Namely: +
+ +
+s6_accessrules_result_t f (char const *key, unsigned int keylen, void *handle, s6_accessrules_params_t *params)
+
+ f looks up key key of length keylen in the database +represented by handle in an implementation-defined way. It returns a +number that says the key has been allowed, denied or not found, or an error +occurred. If the key has been allowed, f stores additional information +from the database into *params. +
+ ++ Two s6_accessrules_backend_func_t functions are natively implemented: +
+ ++ A s6_accessrules_keycheck_func_t is the type of a function that +takes a user-level key, makes a list of corresponding backend-level keys and +calls a s6_accessrules_backend_func_t function until it finds +a match. Namely: +
+ +
+s6_accessrules_result_t f (void const *key, void *handle, s6_accessrules_params_t *params, s6_accessrules_backend_func_t *backend)
+
+ f derives a list of low-level keys to check from key. +Then, for each key k of length klen in this list, it calls +(*backend)(k, klen, handle, params), returning *backend's result if it +is not S6_ACCESSRULES_NOTFOUND. If no match can be found in the whole list, +f finally returns S6_ACCESSRULES_NOTFOUND. +
+ ++ Five s6_accessrules_keycheck_func_t functions are natively implemented: +
+ +
+ s6_accessrules_result_t s6_accessrules_uidgid_cdb
+(unsigned int u, unsigned int g, struct cdb *c,
+s6_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for uid u
+and gid g. If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_uidgid_fs
+(unsigned int u, unsigned int g, char const *dir,
+s6_accessrules_params_t *params)
+Checks the dir base directory for an authorization for uid u
+and gid g. If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_reversedns_cdb
+(char const *name, struct cdb *c,
+s6_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the
+name FQDN. If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_reversedns_fs
+(char const *name, char const *dir,
+s6_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the
+name FQDN. If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip4_cdb
+(char const *ip4, struct cdb *c,
+s6_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the
+ip4 IPv4 address (4 network byte order characters).
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip4_fs
+(char const *ip4, char const *dir,
+s6_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the
+ip4 IPv4 address (4 network byte order characters).
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip6_cdb
+(char const *ip6, struct cdb *c,
+s6_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the
+ip6 IPv6 address (16 network byte order characters).
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip6_fs
+(char const *ip6, char const *dir,
+s6_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the
+ip6 IPv6 address (16 network byte order characters).
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip46_cdb
+(ip46_t *ip, struct cdb *c,
+s6_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the
+ip IP address.
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+ s6_accessrules_result_t s6_accessrules_ip46_fs
+(ip46_t const *ip, char const *dir,
+s6_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the
+ip IP address.
+If the result is S6_ACCESSRULES_ALLOW, additional
+information may be stored into params.
+
+libs6
+s6
+Software
+skarnet.org
+
+ The ftrigr library provides an API for listeners, i.e. +programs that want to subscribe to fifodirs and be instantly +notified when the proper sequence of events happens. +
+ ++ Check the s6/ftrigr.h header for the +exact function prototypes. +
+ ++ Make sure your application is not disturbed by children it doesn't +know it has. This means paying some attention to the SIGCHLD handler, +if any, and to the way you perform waitpid()s. The best +practice is to use a +self-pipe +to handle SIGCHLD (as well as other signals the application needs to trap), +and to always use wait_nohang() to reap children, +simply ignoring pids you don't know. +
+ ++ If your (badly programmed) application has trouble handling unknown +children, consider using a ftrigrd service. +
+ ++ The src/pipe-tools/s6-ftrig-listen1.c and +src/supervision/s6-svwait.c files in the s6 package, +for instance, illustrate how to use the ftrigr library. +
+ + ++ftrigr_t a = FTRIGR_ZERO ; +tain_t deadline, stamp ; + +tain_now(&stamp) ; +tain_addsec(&deadline, &stamp, 2) + +// char const *path = FTRIGR_IPCPATH ; +// ftrigr_start(&a, path, &deadline, &stamp) ; +ftrigr_startf(&a, &deadline, &stamp) ; ++ +
+ftrigr_start starts a session with a ftrigrd service listening on
+path.
+ftrigr_startf starts a session with a ftrigrd process as a child
+(which is the simplest usage).
+a is a ftrigr_t structure that must be declared in the stack and
+initialized to FTRIGR_ZERO.
+stamp must be an accurate enough timestamp.
+If the session initialization fails, the function returns 0 and errno is set;
+else the function returns 1.
+
+If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between stamp and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +
+ ++ You can have more than one session open in parallel, by declaring +several distinct ftrigr_t structures and calling +ftrigr_startf (or ftrigr_start) more than once. +However, this is useless, since one single session can handle +virtually as many concurrent fifodirs as your application needs. +
+ ++ftrigr_end(&a) ; ++ +
+ftrigr_end frees all the resources used by the session. The +a structure is then reusable for another session. +
+ ++char const *path = "/var/lib/myservice/fifodir" ; +char const *re = "a.*b|c*d" ; +uint32 options = 0 ; + +uint16 id = ftrigr_subscribe (&a, path, re, options, &deadline, &stamp) ; ++ +
+ftrigr_subscribe instructs the +s6-ftrigrd daemon, related to the open +session represented by the a structure, to subscribe to the +path fifodir, and to notify the application when it receives +a series of events that matches the re regexp. +options can be 0 or FTRIGR_REPEAT. If it is 0, the daemon will +automatically unsubscribe from path once re has been +matched by a series of events. If it is FTRIGR_REPEAT, it will remain +subscribed until told otherwise. +
+ ++ ftrigr_subscribe() returns 0 and sets errno in case of failure, or +a nonzero 16-bit number identifying the subscription in case of success. +
+ ++ftrigr_subscribe should return near-instantly, but if +deadline is reached, it will return 0 ETIMEDOUT. If +ftrigr_subscribe returns successfully, then the +s6-ftrigrd daemon is guaranteed to be listening on path, +and events can be sent without the risk of a race condition. +
+ ++uint16 list[1] ; +unsigned int n = 1 ; +char trigger ; +list[0] = id ; + +// r = ftrigr_wait_and(&a, list, n, &deadline) ; +r = ftrigr_wait_or(&a, list, n, &deadline, &trigger) ; ++ +
+ ftrigr_wait_and() waits for all the n fifodirs
+whose ids are listed in list to receive an event. It returns -1
+in case of error or timeout, or a non-negative integer in case of success.
+ ftrigr_wait_or() waits for one of the n fifodirs
+whose ids are listed in list to receive an event. It returns -1
+in case of error or timeout; if it succeeds, the return value is the
+position in list, starting at 0, of the identifier that received
+an event; and trigger is set to the character that triggered that
+event, i.e. the last character of a sequence that matched the regular
+expression re used in the subscription.
+
+ (from now on, the functions are listed with their prototypes instead +of usage examples.) +
+ ++int ftrigr_fd (ftrigr_t const *a) ++ +
+ Returns a file descriptor to select on for reading. Do not +read() it though. +
+ ++int ftrigr_update (ftrigr_t *a) ++ +
+ Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6-ftrigrd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +
+ ++ When ftrigr_update returns, +genalloc_s(uint16, &a->list) points to an array of +genalloc_len(uint16, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +ftrigr_check. +
+ ++int ftrigr_check (ftrigr_t *a, uint16 id, char *what) ++ +
+ Checks whether an event happened to id. Use after a +call to ftrigr_update(). +
+ +
+libs6
+s6
+Software
+skarnet.org
+
+ The ftrigw library provides an API for notifiers, i.e. +programs that want to regularly announce what they're doing. +
+ ++ Notifiers should create a fifodir in a hardcoded place in the +filesystem, and document its location. Listeners will then be +able to subscribe to that fifodir, and receive the events. +
+ ++ Check the s6/ftrigw.h header for the +exact function prototypes. +
+ ++char const *path = "/var/lib/myservice/fifodir" ; +int gid = -1 ; +int forceperms = 0 ; +int r = ftrigw_fifodir_make(path, gid, forceperms) ; ++ +
+ftrigw_fifodir_make creates a fifodir at the path location.
+It returns 0, and sets errno, if an error occurs.
+It returns 1 if it succeeds.
+If a fifodir, owned by the user, already exists at path, and
+forceperms is zero, then ftrigw_fifodir_make immediately
+returns a success. If forceperms is nonzero, then
+it tries to adjust path's permissions before returning.
+
+If gid is negative, then path is created "public". +Any listener will be able to subscribe to path. +If gid is nonnegative, then path is created "private". +Only processes belonging to group gid will be able to +subscribe to path. +
+ ++char event = 'a' ; +r = ftrigw_notify(path, event) ; ++ +
+ftrigw_notify sends event to all the processes that are +currently subscribed to path. +It returns -1 if an error occurs, or the number of successfully notified +processes. +
+ ++When stray KILL signals hit s6-ftrigrd processes, +1. it's a sign of incorrect system administration, 2. they can leave +unused named pipes in the fifodir. It's the fifodir's owner's job, i.e. +the notifier's job, to periodically do some housecleaning and remove +those unused pipes. +
+ ++r = ftrigw_clean(path) ; ++ +
+ftrigw_clean cleans path. It returns 0, and sets errno, +if it encounters an error. It returns 1 if it succeeds. +
+ + + diff --git a/doc/libs6/index.html b/doc/libs6/index.html new file mode 100644 index 0000000..9fe7e65 --- /dev/null +++ b/doc/libs6/index.html @@ -0,0 +1,72 @@ + + + + +
+s6
+Software
+skarnet.org
+
+ libs6 is a collection of utility +C interfaces, used in the s6 executables. +
+ ++ The s6/s6.h header is actually a +concatenation of other headers: +the libs6net is separated into several modules, each of them with its +own header. +
+ +
+libs6
+s6
+Software
+skarnet.org
+
+s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well +as regular expressions on events. It takes orders from its client program that controls +it via the ftrigr library, and notifies it when desired +events happen. +
+ ++ s6-ftrigrd is not meant to be called directly. +
+ ++ s6-ftrigrd handles the grunt work of creating fifos in a +fifodir for a subscriber. It also wakes up on every +event, and compares the chain of events it received on a given fifodir with the +client-provided regexp. If the chain of events matches the regexp, it notifies +the client. +
+ ++ The connection management between the client and s6-ftrigrd is entirely done +by the skaclient +library. +
+ ++ s6-ftrigrd is entirely asynchronous. It stores unread notifications into heap +memory; it can grow in size if there are a lot of events and the client fails +to read them. To avoid uncontrolled growth, make sure your client calls +ftrigr_update() as soon as ftrigr_fd() becomes readable. +
+ ++ A s6-ftrigrd instance can only handle up to FTRIGRD_MAX (defined in s6/ftrigr.h) +subscriptions at once. By default, this number is 1000, which is more than enough for +any reasonable system. +
+ + + diff --git a/doc/libs6/s6lock.html b/doc/libs6/s6lock.html new file mode 100644 index 0000000..ca22fe4 --- /dev/null +++ b/doc/libs6/s6lock.html @@ -0,0 +1,238 @@ + + + + +
+libs6
+s6
+Software
+skarnet.org
+
+ s6lock is a C interface to timed locks. Unix natively provides +locks, but the locking primitives are synchronous, so either they are +unbounded in execution time or they require polling. s6lock provides +poll-free locks that can timeout during attempted acquisition. +
+ ++s6lock_t a = S6LOCK_ZERO ; +tain_t deadline ; + +tain_now_g() ; +tain_addsec_g(&deadline, 2) + +char const *path = S6LOCK_IPCPATH ; +s6lock_start_g(&a, path, &deadline) ; +// char const *lockdir = "/tmp/lock" ; +// s6lock_startf_g(&a, lockdir, &deadline) ; ++ +
+s6lock_start_g starts a session by connecting to a s6lockd service
+listening on path. The working directory is set by the administrator
+of the service.
+s6lock_startf_g starts a session with a s6lockd process as a child,
+using lockdir as its working directory.
+
+a is a s6lock_t structure that must be declared in the stack and
+initialized to S6LOCK_ZERO.
+If the session initialization fails, the function returns 0 and errno is set;
+else the function returns 1.
+
+If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between the current time and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +
+ ++ You can have more than one session open in parallel, by declaring +several distinct s6lock_t structures and calling +s6lock_startf_g (or s6lock_start_g) more than once. +However, one single session can handle +virtually as many concurrent locks as your application needs, so +opening several sessions is only useful if you need to acquire locks +in various distinct lock directories. +
+ ++s6lock_end(&a) ; ++ +
+s6lock_end frees all the resources used by the session. The +a structure is then reusable for another session. +
+ ++uint16 id ; +char const *file = "lockfile" ; +tain_t limit ; +tain_t deadline ; + +int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ; +/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */ +r = s6lock_release_g(&a, id, &deadline) ; ++ +
+s6lock_acquire_sh_g instructs the +s6lockd daemon, related to the open +session represented by the a handle, to try and acquire a +shared lock on the +file file located under that daemon's working directory +(typically /var/lock). file will be interpreted as +relative to the daemon's working directory even if it starts with a +slash; however, slashes in the middle of file are likely to +result in an error. +
+ ++limit and deadline are two absolute dates. +deadline is a deadline for the execution of the +function: if by deadline the function has not returned, +then it instantly returns 0 and sets errno to ETIMEDOUT. The +function is normally near-instantaneous, so deadline can +be very close in the future and serves only as a protection against +malicious servers. limit is the acquisition deadline: if +by limit the daemon still has not been able to acquire a lock +on file, then it will report a timeout to the client. +
+ ++The function returns 1 in case of success, or 0 if an error occurs, +with errno set to a suitable value. If it succeeds, then a 16-bit +number is stored into *id; this number serves as an identifier +for this lock. +
+ ++s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, +except that the daemon tries to acquire an exclusive lock. +
+ ++s6lock_release_g releases the lock identified by id. +It normally returns 1. It can return 0 with errno set to a suitable +value if it fails. id is not valid after the corresponding +lock has been released. The function normally returns instantly, with +deadline as a safeguard. +
+ ++ (from now on, the functions are listed with their prototypes instead +of usage examples.) +
+ ++int s6lock_fd (s6lock_t const *a) ++ +
+ Returns a file descriptor to select on for reading. Do not +read() it though. +
+ ++int s6lock_update (s6lock_t *a) ++ +
+ Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6lockd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +
+ ++ When s6lock_update returns, +genalloc_s(uint16, &a->list) points to an array of +genalloc_len(uint16, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +s6lock_check. +
+ ++int s6lock_check (s6lock_t *a, uint16 id, char *what) ++ +
+ Checks whether the lock identified by id has +been acquired. Use after a call to s6lock_update(). +
+ +
+ int s6lock_wait_or_g (s6lock_t *a, uint16 const *idlist, unsigned int n, tain_t const *deadline)
+Synchronously waits for one of the locks represented by the array pointed to
+by idlist of length n to be acquired. Returns -1 if it fails,
+or a nonnegative number on success, which is the index in idlist of the
+acquired lock's id. If no result has been obtained by deadline, the
+function returns -1 ETIMEDOUT.
+
+ int s6lock_wait_and_g (s6lock_t *a, uint16 const *idlist, unsigned int n, tain_t const *deadline)
+Synchronously waits for all of the locks represented by the array pointed to
+by idlist of length n to be acquired. Returns -1 if it fails and
+0 if it succeeds. If no result has been obtained by deadline, the
+function returns -1 ETIMEDOUT.
+
+s6lockd-helper is a helper program for the s6lock daemon. +It just acquires a lock and holds it until it is killed or told to +exit by its parent daemon. +
+ ++ s6lockd-helper is not meant to be invoked directly by the user: +it will be spawned by the +s6lockd program. +
+ ++s6lockd is the s6lock daemon. It is a program that manages +a set of lock files in a given directory, and associated timeouts. +
+ ++ s6lockd does not fork, does not background itself automatically, +and does not use syslog. It is not meant to be run directly by the +user: it will be spawned by the +s6lock client library. +
+ ++ There are 2 ways to use s6lockd: +
+ ++When run as a service, s6lockd has no "standalone" mode: it is +designed to work with a Unix +domain superserver, like +s6-ipcserver. +s6lockd follows the UCSPI +interface, it can be directly executed from the superserver. +
+ +
-s6
-Software
-skarnet.org
-
- libs6lock is a C interface to timed locks. Unix natively provides -locks, but the locking primitives are synchronous, so either they are -unbounded in execution time or they require polling. libs6lock provides -poll-free locks that can timeout during attempted acquisition. -
- --s6lock_t a = S6LOCK_ZERO ; -tain_t deadline ; - -tain_now_g() ; -tain_addsec_g(&deadline, 2) - -char const *path = S6LOCK_IPCPATH ; -s6lock_start_g(&a, path, &deadline) ; -// char const *lockdir = "/tmp/lock" ; -// s6lock_startf_g(&a, lockdir, &deadline) ; -- -
-s6lock_start_g starts a session by connecting to a s6lockd service
-listening on path. The working directory is set by the administrator
-of the service.
-s6lock_startf_g starts a session with a s6lockd process as a child,
-using lockdir as its working directory.
-
-a is a s6lock_t structure that must be declared in the stack and
-initialized to S6LOCK_ZERO.
-If the session initialization fails, the function returns 0 and errno is set;
-else the function returns 1.
-
-If the absolute time deadline is reached and the function -has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. - -Only local interprocess communications are involved; unless your system is -heavily overloaded, the function should return near-instantly. One or two -seconds of delay between the current time and deadline should be -enough: if the function takes more than that to return, then there is a -problem with the underlying processes. -
- -- You can have more than one session open in parallel, by declaring -several distinct s6lock_t structures and calling -s6lock_startf_g (or s6lock_start_g) more than once. -However, one single session can handle -virtually as many concurrent locks as your application needs, so -opening several sessions is only useful if you need to acquire locks -in various distinct lock directories. -
- --s6lock_end(&a) ; -- -
-s6lock_end frees all the resources used by the session. The -a structure is then reusable for another session. -
- --uint16 id ; -char const *file = "lockfile" ; -tain_t limit ; -tain_t deadline ; - -int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ; -/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */ -r = s6lock_release_g(&a, id, &deadline) ; -- -
-s6lock_acquire_sh_g instructs the -s6lockd daemon, related to the open -session represented by the a handle, to try and acquire a -shared lock on the -file file located under that daemon's working directory -(typically /var/lock). file will be interpreted as -relative to the daemon's working directory even if it starts with a -slash; however, slashes in the middle of file are likely to -result in an error. -
- --limit and deadline are two absolute dates. -deadline is a deadline for the execution of the -function: if by deadline the function has not returned, -then it instantly returns 0 and sets errno to ETIMEDOUT. The -function is normally near-instantaneous, so deadline can -be very close in the future and serves only as a protection against -malicious servers. limit is the acquisition deadline: if -by limit the daemon still has not been able to acquire a lock -on file, then it will report a timeout to the client. -
- --The function returns 1 in case of success, or 0 if an error occurs, -with errno set to a suitable value. If it succeeds, then a 16-bit -number is stored into *id; this number serves as an identifier -for this lock. -
- --s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, -except that the daemon tries to acquire an exclusive lock. -
- --s6lock_release_g releases the lock identified by id. -It normally returns 1. It can return 0 with errno set to a suitable -value if it fails. id is not valid after the corresponding -lock has been released. The function normally returns instantly, with -deadline as a safeguard. -
- -- (from now on, the functions are listed with their prototypes instead -of usage examples.) -
- --int s6lock_fd (s6lock_t const *a) -- -
- Returns a file descriptor to select on for reading. Do not -read() it though. -
- --int s6lock_update (s6lock_t *a) -- -
- Call this function whenever the fd checks readability: it will -update a's internal structures with information from the -s6lockd daemon. It returns -1 if an error -occurs; in case of success, it returns the number of identifiers for -which something happened. -
- -- When s6lock_update returns, -genalloc_s(uint16, &a->list) points to an array of -genalloc_len(uint16, &a->list) 16-bit unsigned -integers. Those integers are ids waiting to be passed to -s6lock_check. -
- --int s6lock_check (s6lock_t *a, uint16 id, char *what) -- -
- Checks whether the lock identified by id has -been acquired. Use after a call to s6lock_update(). -
- -
- int s6lock_wait_or_g (s6lock_t *a, uint16 const *idlist, unsigned int n, tain_t const *deadline)
-Synchronously waits for one of the locks represented by the array pointed to
-by idlist of length n to be acquired. Returns -1 if it fails,
-or a nonnegative number on success, which is the index in idlist of the
-acquired lock's id. If no result has been obtained by deadline, the
-function returns -1 ETIMEDOUT.
-
- int s6lock_wait_and_g (s6lock_t *a, uint16 const *idlist, unsigned int n, tain_t const *deadline)
-Synchronously waits for all of the locks represented by the array pointed to
-by idlist of length n to be acquired. Returns -1 if it fails and
-0 if it succeeds. If no result has been obtained by deadline, the
-function returns -1 ETIMEDOUT.
-
-s6lockd-helper is a helper program for the s6lock daemon. -It just acquires a lock and holds it until it is killed or told to -exit by its parent daemon. -
- -- s6lockd-helper is not meant to be invoked directly by the user: -it will be spawned by the -s6lockd program. -
- --s6lockd is the s6lock daemon. It is a program that manages -a set of lock files in a given directory, and associated timeouts. -
- -- s6lockd does not fork, does not background itself automatically, -and does not use syslog. It is not meant to be run directly by the -user: it will be spawned by the -s6lock client library. -
- -- There are 2 ways to use s6lockd: -
- --When run as a service, s6lockd has no "standalone" mode: it is -designed to work with a Unix -domain superserver, like -s6-ipcserver. -s6lockd follows the UCSPI -interface, it can be directly executed from the superserver. -
- -
+s6
+Software
+skarnet.org
+
+ A local service is a daemon that listens to incoming connections +on a Unix domain socket. Clients of the service are programs connecting to +this socket: the daemon performs operations on their behalf. +
+ ++ The service is called local because it is not accessible to +clients from the network. +
+ ++ A widely known example of a local service is the syslogd daemon. +On most implementations, it listens to the /dev/log socket. +Its clients connect to it and send their logs via the socket. The +openlog() function is just a wrapper arround the connect() +system call, the syslog() function a wrapper around write(), +and so on. +
+ ++ The most important benefit of a local service is that it permits +controlled privilege gains without using setuid programs. +The daemon is run as user S; a client running as user C and connecting to +the daemon asks it to perform operations: those will be done as user S. +
+ ++ Standard Unix permissions on the listening socket can be used to implement +some basic access control: to restrict access to clients belonging to group +G, change the socket to user S and group G, and give it 0420 permissions. +This is functionally equivalent to the basic access control for setuid +programs: a program having user S, group G and permissions 4750 will be +executable by group G and run with S rights. +
+ ++ But modern systems implement the +getpeereid() +system call or library function. This function allows the server to know the +client's credentials: so fine-grained access control is possible. On those +systems, local services can do as much authentication as setuid programs, +in a much more controlled environment. +
+ ++ The most obvious difference between a local service and a network service +is that a local service does not serve network clients. But local services +have another nice perk: while network services usually only provide you +with a single channel (a TCP or UDP socket) of communication between the +client and the server, forcing you to multiplex your data into that +channel, local services allow you to have as many +communication channels as you want. +
+ ++(The SCTP transport layer provides a way for network services to use +several communication channels. Unfortunately, it is not widely deployed +yet, and a lot of network services still depend on TCP.) +
+ ++ The fd-passing mechanism is Unix domain socket black magic +that allows one peer of the socket to send open file descriptors to +the other peer. So, if the server opens a pipe and sends one end of +this pipe to a client via this mechanism, there is effectively a +socket and a pipe between the client and the server. +
+ ++ The UCSPI protocol +is an easy way of abstracting clients and servers from the network. +A server written as a UCSPI server, just as it can be run +under inetd or +s6-tcpserver, +can be run under +s6-ipcserver: choose a socket +location and you have a local service. +
+ ++ Fine-grained access control can be added by inserting +s6-ipcserver-access in +your server command line after s6-ipcserver. +
+ ++ A client written as an UCSPI client, i.e. assuming it has descriptor +6 (resp. 7) open and reading from (resp. writing to) the server socket, +can be run under s6-ipcclient. +
+ ++ skarnet.org libraries often use a separate process to handle +asynchronicity and background work in a way that's invisible to +the user. Among them are: +
+ ++ Those processes are usually spawned from a client, via the corresponding +*_startf*() library call. But they can also be spawned from a +s6-ipcserver program in a local service configuration. In both cases, they +need an additional control channel to be passed from the server to +the client: the main socket is used for synchronous commands from the client +to the server and their answers, whereas the additional channel, which is +now implemented as a socket as well (but created by the server on-demand +and not bound to a local path), is used for asynchronous +notifications from the server to the client. The fd-passing mechanism +is used to transfer the additional channel from the server to the client. +
+ + + diff --git a/doc/s6-accessrules-cdb-from-fs.html b/doc/s6-accessrules-cdb-from-fs.html new file mode 100644 index 0000000..f7b6be0 --- /dev/null +++ b/doc/s6-accessrules-cdb-from-fs.html @@ -0,0 +1,141 @@ + + + + +
+s6
+Software
+skarnet.org
+
+s6-accessrules-cdb-from-fs compiles a directory +containing a ruleset suitable for +s6-ipcserver-access or +s6-tcpserver-access into a +CDB file. +
+ ++ s6-accessrules-cdb-from-fs cdbfile dir ++ +
+ To be understood by s6-accessrules-cdb-from-fs, +s6-ipcserver-access, or +s6-tcpserver-access, +dir must have a specific format. +
+ ++ dir contains a series of directories: +
+ ++Depending on the application, other directories can appear in dir +and be compiled into cdbfile, but +s6-tcpserver-access only +uses the first three, and +s6-ipcserver-access only +uses the last two. +
+ ++ Each of those directories contains a set of rules. A rule is +a subdirectory named after the set of keys it matches, and containing +actions that will be executed if the rule is the first matching rule +for the tested key. +
+ ++ The syntax for the rule name is dependent on the nature of keys, and +fully documented on the +accessrules +library page. For instance, a subdirectory named 192.168.0.0_27 +in the ip4 directory will match every IPv4 address in the +192.168.0.0/27 network that does not match a more precise rule. +
+ ++ The syntax for the actions, however, is the same for every type of key. +A rule subdirectory can contain the following elements: +
+ +
+s6
+Software
+skarnet.org
+
+s6-accessrules-fs-from-cdb decompiles a CDB database +containing a ruleset suitable for +s6-ipcserver-access or +s6-tcpserver-access and +that has been compiled with +s6-accessrules-cdb-from-fs. +
+ ++ s6-accessrules-fs-from-cdb dir cdbfile ++ +
In normal use, it is not necessary to call s6-cleanfifodir. However, stale -FIFOs can be left by s6-ftrigrd processes that +FIFOs can be left by s6-ftrigrd processes that were violently killed, so it's good practice to regularly clean up fifodirs.
diff --git a/doc/s6-connlimit.html b/doc/s6-connlimit.html new file mode 100644 index 0000000..fc316cf --- /dev/null +++ b/doc/s6-connlimit.html @@ -0,0 +1,107 @@ + + + + +
+s6
+Software
+skarnet.org
+
+s6-connlimit is a small utility to perform IP-based +control on the number of client connections to a TCP socket, and +uid-based control on the number of client connections to a Unix +domain socket. +
+ ++ s6-connlimit prog... ++ +
+ The s6-tcpserver4 and +s6-tcpserver6 define the PROTO environment +variable to "TCP", and spawn every child server with the TCPCONNNUM environment +variable set to the number of connections from the same IP address. + The s6-tcpserver-access program +can set environment variables depending on the client's IP address. If the +s6-tcpserver-access database is configured to set the TCPCONNMAX environment +variable for a given set of IP addresses, and s6-tcpserver-access execs into +s6-connlimit, then s6-connlimit will drop connections if there already are +${TCPCONNMAX} connections from the same client IP address. +
+ ++ The s6-ipcserver and +s6-ipcserver-access programs can +be used the same way, with "IPC" instead of "TCP", to limit the number +of client connections by UID. +
+ ++ The following command line: +
+ ++ s6-tcpserver4 -v2 -c1000 -C40 1.2.3.4 80 \ + s6-tcpserver-access -v2 -RHl0 -i dir \ + s6-connlimit \ + prog... ++ +
+ will run a server listening to IPv4 address 1.2.3.4, on port 80, +serving up to 1000 concurrent connections, and up to 40 concurrent +connections from the same IP address, no matter what the IP address. +For every client connection, it will look up the database set up +in dir; if the connection is accepted, it will run prog.... +
+ ++ If the dir/ip4/5.6.7.8_32/env/TCPCONNMAX file +exists and contains the string 30, then at most 30 concurrent +connections from 5.6.7.8 will execute prog..., instead of the +default of 40. +
+ +s6-ftrig-notify cannot be used to send the null character (event 0x00). If you need to send the null character, use the C API: -ftrigw_notify(). +ftrigw_notify().
-s6
-Software
-skarnet.org
-
-s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well -as regular expressions on events. It takes orders from its client program that controls -it via the ftrigr library, and notifies it when desired -events happen. -
- -- s6-ftrigrd is not meant to be called directly. -
- -- s6-ftrigrd handles the grunt work of creating fifos in a -fifodir for a subscriber. It also wakes up on every -event, and compares the chain of events it received on a given fifodir with the -client-provided regexp. If the chain of events matches the regexp, it notifies -the client. -
- -- The connection management between the client and s6-ftrigrd is entirely done -by the skaclient -library. -
- -- s6-ftrigrd is entirely asynchronous. It stores unread notifications into heap -memory; it can grow in size if there are a lot of events and the client fails -to read them. To avoid uncontrolled growth, make sure your client calls -ftrigr_update() as soon as ftrigr_fd() becomes readable. -
- -- A s6-ftrigrd instance can only handle up to FTRIGRD_MAX (defined in s6/ftrigr.h) -subscriptions at once. By default, this number is 1000, which is more than enough for -any reasonable system. -
- -