├── LICENSE ├── Makefile ├── README.md ├── man7 ├── s6-accessrules.7 ├── s6-fdholder-error-codes.7 ├── s6-fdholder.7 ├── s6-fifodir.7 ├── s6-ftrigr.7 ├── s6-ftrigw.7 ├── s6-instanced-service.7 ├── s6-libftrig.7 ├── s6-libs6.7 ├── s6-local-service.7 ├── s6-notifywhenup.7 ├── s6-overview.7 ├── s6-s6lock.7 ├── s6-scan-directory.7 ├── s6-service-directory.7 ├── s6-socket-activation.7 ├── s6-svscan-as-process-1.7 └── s6-svscan-not-as-process-1.7 └── man8 ├── s6-accessrules-cdb-from-fs.8 ├── s6-accessrules-fs-from-cdb.8 ├── s6-applyuidgid.8 ├── s6-cleanfifodir.8 ├── s6-connlimit.8 ├── s6-envdir.8 ├── s6-envuidgid.8 ├── s6-fdholder-daemon.8 ├── s6-fdholder-delete.8 ├── s6-fdholder-getdump.8 ├── s6-fdholder-list.8 ├── s6-fdholder-retrieve.8 ├── s6-fdholder-setdump.8 ├── s6-fdholder-store.8 ├── s6-fdholder-transferdump.8 ├── s6-fdholderd.8 ├── s6-fghack.8 ├── s6-ftrig-listen.8 ├── s6-ftrig-listen1.8 ├── s6-ftrig-notify.8 ├── s6-ftrig-wait.8 ├── s6-ftrigrd.8 ├── s6-instance-control.8 ├── s6-instance-create.8 ├── s6-instance-delete.8 ├── s6-instance-list.8 ├── s6-instance-maker.8 ├── s6-instance-status.8 ├── s6-ioconnect.8 ├── s6-ipcclient.8 ├── s6-ipcserver-access.8 ├── s6-ipcserver-socketbinder.8 ├── s6-ipcserver.8 ├── s6-ipcserverd.8 ├── s6-log.8 ├── s6-mkfifodir.8 ├── s6-notifyoncheck.8 ├── s6-permafailon.8 ├── s6-setlock.8 ├── s6-setsid.8 ├── s6-setuidgid.8 ├── s6-socklog.8 ├── s6-softlimit.8 ├── s6-sudo.8 ├── s6-sudoc.8 ├── s6-sudod.8 ├── s6-supervise.8 ├── s6-svc.8 ├── s6-svdt-clear.8 ├── s6-svdt.8 ├── s6-svlink.8 ├── s6-svlisten.8 ├── s6-svlisten1.8 ├── s6-svok.8 ├── s6-svperms.8 ├── s6-svscan.8 ├── s6-svscanctl.8 ├── s6-svstat.8 ├── s6-svunlink.8 ├── s6-svwait.8 ├── s6-tai64n.8 ├── s6-tai64nlocal.8 ├── s6-usertree-maker.8 ├── s6lockd-helper.8 ├── s6lockd.8 └── ucspilogd.8 /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2011-2023 Laurent Bercot 2 | Copyright (c) 2020-2023 Alexis 3 | 4 | Permission to use, copy, modify, and distribute this software for any 5 | purpose with or without fee is hereby granted, provided that the above 6 | copyright notice and this permission notice appear in all copies. 7 | 8 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14 | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | DESTDIR = 2 | PREFIX = /usr 3 | MAN_DIR ?= $(PREFIX)/share/man 4 | man7_dir = $(MAN_DIR)/man7 5 | man8_dir = $(MAN_DIR)/man8 6 | 7 | man7_targets = \ 8 | s6-accessrules.7 \ 9 | s6-fdholder-error-codes.7 \ 10 | s6-fdholder.7 \ 11 | s6-fifodir.7 \ 12 | s6-ftrigr.7 \ 13 | s6-ftrigw.7 \ 14 | s6-instanced-service.7 \ 15 | s6-libftrig.7 \ 16 | s6-libs6.7 \ 17 | s6-local-service.7 \ 18 | s6-notifywhenup.7 \ 19 | s6-overview.7 \ 20 | s6-s6lock.7 \ 21 | s6-scan-directory.7 \ 22 | s6-service-directory.7 \ 23 | s6-socket-activation.7 \ 24 | s6-svscan-as-process-1.7 \ 25 | s6-svscan-not-as-process-1.7 26 | 27 | man8_targets = \ 28 | s6-accessrules-cdb-from-fs.8 \ 29 | s6-accessrules-fs-from-cdb.8 \ 30 | s6-applyuidgid.8 \ 31 | s6-cleanfifodir.8 \ 32 | s6-connlimit.8 \ 33 | s6-envdir.8 \ 34 | s6-envuidgid.8 \ 35 | s6-fdholder-daemon.8 \ 36 | s6-fdholder-delete.8 \ 37 | s6-fdholder-getdump.8 \ 38 | s6-fdholder-list.8 \ 39 | s6-fdholder-retrieve.8 \ 40 | s6-fdholder-setdump.8 \ 41 | s6-fdholder-store.8 \ 42 | s6-fdholder-transferdump.8 \ 43 | s6-fdholderd.8 \ 44 | s6-fghack.8 \ 45 | s6-ftrig-listen.8 \ 46 | s6-ftrig-listen1.8 \ 47 | s6-ftrig-notify.8 \ 48 | s6-ftrig-wait.8 \ 49 | s6-ftrigrd.8 \ 50 | s6-instance-control.8 \ 51 | s6-instance-create.8 \ 52 | s6-instance-delete.8 \ 53 | s6-instance-list.8 \ 54 | s6-instance-maker.8 \ 55 | s6-instance-status.8 \ 56 | s6-ioconnect.8 \ 57 | s6-ipcclient.8 \ 58 | s6-ipcserver-access.8 \ 59 | s6-ipcserver-socketbinder.8 \ 60 | s6-ipcserver.8 \ 61 | s6-ipcserverd.8 \ 62 | s6-log.8 \ 63 | s6-mkfifodir.8 \ 64 | s6-notifyoncheck.8 \ 65 | s6-permafailon.8 \ 66 | s6lockd.8 \ 67 | s6-setlock.8 \ 68 | s6-setsid.8 \ 69 | s6-setuidgid.8 \ 70 | s6-socklog.8 \ 71 | s6-softlimit.8 \ 72 | s6-sudo.8 \ 73 | s6-sudoc.8 \ 74 | s6-sudod.8 \ 75 | s6-supervise.8 \ 76 | s6-svc.8 \ 77 | s6-svdt-clear.8 \ 78 | s6-svdt.8 \ 79 | s6-svlink.8 \ 80 | s6-svlisten.8 \ 81 | s6-svlisten1.8 \ 82 | s6-svok.8 \ 83 | s6-svperms.8 \ 84 | s6-svscan.8 \ 85 | s6-svscanctl.8 \ 86 | s6-svstat.8 \ 87 | s6-svunlink.8 \ 88 | s6-svwait.8 \ 89 | s6-tai64n.8 \ 90 | s6-tai64nlocal.8 \ 91 | s6-usertree-maker.8 \ 92 | s6lockd-helper.8 \ 93 | ucspilogd.8 94 | 95 | all: 96 | @echo "Nothing to be done. Ready for 'make install'." 97 | 98 | install: 99 | cd man7; install -D -m 0644 -t ${DESTDIR}${man7_dir} $(man7_targets) 100 | cd man8; install -D -m 0644 -t ${DESTDIR}${man8_dir} $(man8_targets) 101 | 102 | uninstall: 103 | cd $(man7_dir); rm -f $(man7_targets) 104 | cd $(man8_dir); rm -f $(man8_targets) 105 | 106 | .PHONY: all install uninstall 107 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | ## NOTE: This repository is now read-only - official repository now at https://git.sr.ht/~flexibeast/s6-man-pages 3 | 4 | This repository provides [mdoc(7)](https://man.openbsd.org/mdoc.7) 5 | ports of the HTML documentation for the [s6 supervision 6 | suite](http://skarnet.org/software/s6/). The HTML version on the s6 7 | site is authoritative; in the event of semantic differences between an 8 | HTML original and its port, please open an issue in this repository. 9 | 10 | To install the man pages, run `make install`. 11 | 12 | The default installation directory is `/usr/share/man`, but this can 13 | be changed by setting the `MAN_DIR` environment variable prior to 14 | running `make`. The user running `make` will need to have the 15 | appropriate permissions for installation in the chosen directory. 16 | 17 | The man pages can be uninstalled by running `make uninstall`. 18 | 19 | HTML versions can be produced with 20 | [mandoc(1)](https://man.openbsd.org/mandoc.1)'s `-T` flag: 21 | 22 | ``` 23 | $ mandoc -T html man8/s6-svscan.8 > s6-svscan.8.html 24 | ``` 25 | -------------------------------------------------------------------------------- /man7/s6-fdholder-error-codes.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-ERROR-CODES 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-error-codes 6 | .Nd error codes returned by the 7 | .Xr s6-fdholderd 8 8 | daemon 9 | .Sh DESCRIPTION 10 | The following error messages (and corresponding 11 | .Xr errno 3 12 | codes) can be returned by the 13 | .Xr s6-fdholderd 8 14 | daemon to its various clients. 15 | This page explains why they occur. 16 | .Bl -bullet -width x 17 | .It 18 | .Ql Protocol error 19 | .Po 20 | .Dv EPROTO 21 | .Pc 22 | or 23 | .Ql Protocol wrong type for socket 24 | .Po 25 | .Dv EPROTOTYPE 26 | .Pc 27 | .Pp 28 | The client connected to the wrong kind of server and they cannot 29 | communicate. 30 | This is generally a programming error. 31 | It can also signal a bug in the s6-fdholder tools, but protocol bugs 32 | have usually been wiped out before an s6 release. 33 | .It 34 | .Ql Broken pipe 35 | .Po 36 | .Dv EPIPE 37 | .Pc 38 | .Pp 39 | The client was not authorized to connect to the server, which closed 40 | the connection. 41 | You need to configure the access rights to the server. 42 | .It 43 | .Ql Operation not permitted 44 | .Po 45 | .Dv EPERM 46 | .Pc 47 | .Pp 48 | Even though the client was authorized to connect to the server, the 49 | specific operation it wanted to perform was denied. 50 | You need to configure the access rights to the server. 51 | .It 52 | .Ql Too many open files in system 53 | .Po 54 | .Dv ENFILE 55 | .Pc 56 | .Pp 57 | The client attempted to store more file descriptors than the server 58 | can hold. 59 | Or, the client attempted to retrieve more file descriptors than it can 60 | hold. 61 | You should check the 62 | .Fl n 63 | option to 64 | .Xr s6-fdholderd 8 , 65 | as well as the 66 | .Dv RLIMIT_NOFILE Ns [1] 67 | resource limits used by the client and the server, and adjust them 68 | accordingly. 69 | .It 70 | .Ql Resource busy 71 | .Po 72 | .Dv EBUSY 73 | .Pc 74 | .Pp 75 | The client attempted to store a descriptor under an identifier that is 76 | already used. 77 | .It 78 | .Ql Filename too long 79 | .Po 80 | .Dv ENAMETOOLONG 81 | .Pc 82 | .Pp 83 | The identifier provided by the client was too long. 84 | .It 85 | .Ql \&No such file or directory 86 | .Po 87 | .Dv ENOENT 88 | .Pc 89 | .Pp 90 | The identifier provided by the client was not found in the server 91 | database. 92 | .It 93 | .Ql Bad file descriptor 94 | .Po 95 | .Dv EBADF 96 | .Pc 97 | .Pp 98 | The client attempted to transmit a closed, or otherwise unsuitable for 99 | fd-passing, file descriptor. 100 | .It 101 | .Ql Operation timed out 102 | .Po 103 | .Dv ETIMEDOUT 104 | .Pc 105 | .Pp 106 | The client, or the server, took too long to perform the wanted 107 | operation. 108 | This is most probably a programming error, because both client and 109 | server should have a very fast reaction time. 110 | Check that the client is connecting to the right server, and check 111 | .Fl t 112 | options to both client and server (the argument is interpreted as 113 | milliseconds!). 114 | .El 115 | .Pp 116 | Other errors indicate a transient error such as lack of memory, 117 | hardware failure, etc. 118 | .Sh SEE ALSO 119 | .Xr s6-fdholder-daemon 8 , 120 | .Xr s6-fdholder-delete 8 , 121 | .Xr s6-fdholder-getdump 8 , 122 | .Xr s6-fdholder-list 8 , 123 | .Xr s6-fdholder-retrieve 8 , 124 | .Xr s6-fdholder-setdump 8 , 125 | .Xr s6-fdholder-store 8 , 126 | .Xr s6-fdholder-transferdump 8 , 127 | .Xr s6-fdholderd 8 128 | .Pp 129 | [1] 130 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_resource.h.html 131 | .Pp 132 | This man page is ported from the authoritative documentation at: 133 | .Lk https://skarnet.org/software/s6/s6-fdholder-errorcodes.html 134 | .Sh AUTHORS 135 | .An Laurent Bercot 136 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 137 | -------------------------------------------------------------------------------- /man7/s6-fdholder.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder 6 | .Nd API for clients wanting to communicate with an 7 | .Xr s6-fdholderd 8 8 | daemon 9 | .Sh DESCRIPTION 10 | Check the 11 | .Pa s6/s6-fdholder.h 12 | header for the exact function prototypes. 13 | .Ss A programming example 14 | The 15 | .Pa src/fdholder/s6-fdholder-*.c 16 | files in the s6 package, for instance, illustrate how to use the 17 | .Nm 18 | library. 19 | .Ss Synchronous functions with a specified maximum execution time 20 | The explanation given in 21 | .Xr s6-ftrigr 7 22 | applies here too: the functions documented in this page are 23 | synchronous, but can return early if the deadline is reached, in which 24 | case the connection to the server should be closed immediately because 25 | no protocol consistency is guaranteed. 26 | .Pp 27 | The 28 | .Xr s6-fdholderd 8 29 | server should be very quick to answer queries, so this mechanism is 30 | provided as a simple security against programming errors - for 31 | instance, connecting to the wrong daemon. 32 | .Ss Starting and ending a session 33 | .Bd -literal -offset indent 34 | s6_fdholder_t a = S6_FDHOLDER_ZERO ; 35 | int fd = 6 ; 36 | 37 | tain_now_g() ; 38 | 39 | s6_fdholder_init(&a, fd) ; 40 | (...) 41 | s6_fdholder_free(&a) ; 42 | .Ed 43 | .Pp 44 | .Fn s6_fdholder_init 45 | assumes that 46 | .Va fd 47 | is a socket already connected to an 48 | .Xr s6-fdholderd 8 49 | daemon. 50 | The 51 | .Va a 52 | structure must be initialized to 53 | .Dv S6_FDHOLDER_ZERO 54 | before use. 55 | .Pp 56 | .Fn tain_now_g 57 | initializes a global variable that keeps track of the current time, 58 | for use with later functions. 59 | .Pp 60 | .Fn s6_fdholder_free 61 | frees the resources occupied by 62 | .Va a . 63 | It does not, however, close 64 | .Va fd . 65 | You should manually close it to end the connection to the server. 66 | Note that if your program has been started by 67 | .Xr s6-ipcclient 8 , 68 | both fds 6 and 7 are open (and refer to the same socket), so you 69 | should close both. 70 | .Pp 71 | Alternatively, if your connection to 72 | .Xr s6-fdholderd 8 73 | has not been created yet, you can use the following functions: 74 | .Bl -bullet -width x 75 | .It 76 | .Ft int 77 | .Fn s6_fdholder_start "s6_fdholder_t *a" "char const *path" "tain_t const *deadline" "tain_t *stamp" 78 | .Pp 79 | Starts a session with an 80 | .Xr s6-fdholderd 8 81 | instance listening on 82 | .Va path . 83 | .Va a 84 | must be initialized to 85 | .Dv S6_FDHOLDER_ZERO 86 | before calling this function. 87 | On success, returns nonzero and 88 | .Va a 89 | can be used as a handle for the next 90 | .Fn s6_fdholder_* 91 | function calls. 92 | On failure, returns 0, and sets errno. 93 | .It 94 | .Ft void 95 | .Fn s6_fdholder_end "s6_fdholder_t *a" 96 | .Pp 97 | Ends the current session and frees all allocated resources. 98 | If needed, 99 | .Va a 100 | is immediately reusable for another 101 | .Fn s6_fdholder_start 102 | call. 103 | .El 104 | .Ss Storing an fd 105 | .Bd -literal -offset indent 106 | int r ; 107 | int fd ; 108 | tain_t limit = TAIN_INFINITE ; 109 | char const *id = "my_identifier" ; 110 | r = s6_fdholder_store_g(&a, fd, id, &limit, &deadline) ; 111 | .Ed 112 | .Pp 113 | .Fn s6_fdholder_store 114 | (and its variant 115 | .Fn s6_fdholder_store_g 116 | that uses the global timestamp variable) attempts to store a copy of 117 | descriptor 118 | .Va fd 119 | into 120 | .Xr s6-fdholderd 8 , 121 | using identifier 122 | .Va id , 123 | with an expiration date of 124 | .Va limit . 125 | In this example, 126 | .Va limit 127 | is 128 | .Dv TAIN_INFINITE , 129 | which means no expiration date. 130 | The operation should return before 131 | .Va deadline , 132 | else it will automatically return 0 133 | .Dv ETIMEDOUT . 134 | The result is 1 on success and 0 on failure, with an appropriate errno 135 | code; refer to 136 | .Xr s6-fdholder-error-codes 7 . 137 | .Ss Deleting an fd 138 | .Dl fd = s6_fdholder_delete_g(&a, id, &deadline) ; 139 | .Pp 140 | .Fn s6_fdholder_delete 141 | attempts to delete the file descriptor identified by 142 | .Va id . 143 | It returns 1 on success and 0 on failure, with an appropriate errno 144 | code; refer to 145 | .Xr s6-fdholder-error-codes 7 . 146 | .Ss Retrieving an fd 147 | .Dl fd = s6_fdholder_retrieve_g(&a, id, &deadline) ; 148 | .Pp 149 | .Fn s6_fdholder_retrieve 150 | attempts to retrieve the file descriptor identified by 151 | .Va id . 152 | It returns a valid fd number on success, and -1 on failure, with an 153 | appropriate errno code; refer to 154 | .Xr s6-fdholder-error-codes 7 . 155 | .Pp 156 | .Fn s6_fdholder_retrieve_delete 157 | performs a retrieval and a deletion at the same time, if the client is 158 | authorized to do so. 159 | .Ss Listing the identifiers held by the server 160 | .Bd -literal -offset indent 161 | stralloc list = STRALLOC_ZERO ; 162 | int n ; 163 | n = s6_fdholder_list_g(&a, &list, &deadline) ; 164 | .Ed 165 | .Pp 166 | .Fn s6_fdholder_list 167 | gets the list of all identifiers currently held by the server. 168 | It stores it into the stralloc[1] 169 | .Va list , 170 | as a series of null-terminated strings, one after the other. 171 | There are 172 | .Va n 173 | such strings. 174 | The function returns 175 | .Va n 176 | on success, or -1 on failure, with an appropriate errno code; refer to 177 | .Xr s6-fdholder-error-codes 7 . 178 | .Ss Reading a dump 179 | .Bd -literal -offset indent 180 | genalloc dump = GENALLOC_ZERO ; 181 | r = s6_fdholder_getdump_g(&a, &dump, &deadline) ; 182 | .Ed 183 | .Pp 184 | .Fn s6_fdholder_getdump 185 | attempts to retrieve the whole set of descriptors from the server. 186 | It returns 1 on success, and 0 on failure, with an appropriate errno 187 | code; refer to 188 | .Xr s6-fdholder-error-codes 7 . 189 | The set is stored into the genalloc[2] 190 | .Va dump , 191 | which is to be interpreted as a stralloc containing an array of 192 | .Vt s6_fdholder_fd_t . 193 | .Pp 194 | .Ql genalloc_s(s6_fdholder_fd_t, &dump) 195 | is a pointer to this array, and 196 | .Ql genalloc_len(s6_fdholder_fd_t, &dump) 197 | is the number of elements in the array. 198 | An 199 | .Vt s6_fdholder_fd_t 200 | contains at least a descriptor number, an identifier, and an 201 | expiration date; see the 202 | .Pa s6/s6-fdholder.h 203 | header file. 204 | .Ss Writing a dump 205 | .Bd -literal -offset indent 206 | unsigned int dumplen ; 207 | s6_fdholder_fd_t const *dumparray ; 208 | r = s6_fdholder_setdump_g(&a, &dumparray, dumplen, &deadline) ; 209 | .Ed 210 | .Pp 211 | .Fn s6_fdholder_setdump 212 | attempts to send a set of descriptors to the server. 213 | The descriptors are contained in the array 214 | .Va dumparray 215 | of length 216 | .Va dumplen . 217 | The function returns 1 on success, and 0 on failure, with an 218 | appropriate errno code; refer to 219 | .Xr s6-fdholder-error-codes 7 . 220 | .Sh SEE ALSO 221 | .Xr s6-accessrules 7 , 222 | .Xr s6-ftrigr 7 , 223 | .Xr s6-ftrigw 7 , 224 | .Xr s6-libs6 7 , 225 | .Xr s6-s6lock 7 226 | .Pp 227 | [1] 228 | .Lk https://skarnet.org/software/skalibs/libstddjb/stralloc.html 229 | .Pp 230 | [2] 231 | .Lk https://skarnet.org/software/skalibs/libstddjb/genalloc.html 232 | .Pp 233 | This man page is ported from the authoritative documentation at: 234 | .Lk https://skarnet.org/software/s6/libs6/s6-fdholder.html 235 | .Sh AUTHORS 236 | .An Laurent Bercot 237 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 238 | -------------------------------------------------------------------------------- /man7/s6-fifodir.7: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt S6-FIFODIR 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fifodir 6 | .Nd rendez-vous point between the notifier of certain events and its listeners 7 | .Sh DESCRIPTION 8 | An 9 | .Nm 10 | is implemented via a directory in the filesystem. 11 | No data is stored; it is appropriate to create fifodirs in a RAM 12 | filesystem. 13 | .Ss C API 14 | For the notifier: 15 | .Bl -bullet -width x 16 | .It 17 | You can create fifodirs via the 18 | .Fn ftrigw_fifodir_create 19 | function in 20 | .Xr s6-ftrigw 7 . 21 | .It 22 | You can send an event to a fifodir via the 23 | .Fn ftrigw_notify 24 | function in the notifier part of 25 | .Xr s6-ftrigw 7 . 26 | .It 27 | You can clean up a fifodir via the 28 | .Fn ftrigw_clean 29 | function in 30 | .Xr s6-ftrigw 7 . 31 | .It 32 | You can destroy fifodirs via the 33 | .Fn rm_rf 34 | function in libstddjb[1]. 35 | .El 36 | .Pp 37 | For a listener: 38 | .Bl -bullet -width x 39 | .It 40 | You can subscribe to a fifodir via the 41 | .Fn ftrigr_subscribe 42 | function in the listener part of the 43 | .Xr s6-ftrigr 7 . 44 | .It 45 | Other functions in 46 | .Xr s6-ftrigr 7 47 | allow you to receive and handle events synchronously or 48 | asynchronously. 49 | .El 50 | .Ss Unix API 51 | For the notifier: 52 | .Bl -bullet -width x 53 | .It 54 | You can create fifodirs with the 55 | .Xr s6-mkfifodir 8 56 | command. 57 | .It 58 | You can send an event to a fifodir with the 59 | .Xr s6-ftrig-notify 8 60 | command. 61 | .It 62 | You can clean up a fifodir with the 63 | .Xr s6-cleanfifodir 8 64 | command. 65 | .It 66 | You can destroy fifodirs with the 67 | .Ql rm -rf 68 | command. 69 | .El 70 | .Pp 71 | For a listener: 72 | .Bl -bullet -width x 73 | .It 74 | You can subscribe to a fifodir and wait for an event, or a series or 75 | events, with the 76 | .Xr s6-ftrig-wait 8 77 | command. 78 | .It 79 | You can subscribe to a fifodir, then trigger a program, then wait for 80 | an event, with the 81 | .Xr s6-ftrig-listen1 8 82 | and 83 | .Xr s6-ftrig-listen 8 84 | commands. 85 | This makes it possible to only send a notification after you're sure a 86 | notifier is actually listening, in order to prevent race conditions. 87 | .El 88 | .Sh IMPLEMENTATION NOTES 89 | .Bl -bullet -width x 90 | .It 91 | Notifiers and listeners agree on a fifodir. 92 | .It 93 | The fifodir directory is created by the notifier. 94 | It must be writable by listeners. 95 | .It 96 | To subscribe, a listener atomically creates a named pipe (FIFO) in 97 | this directory and listens to the reading end. 98 | This named pipe must be writable by the notifier. 99 | .It 100 | To send an event to listeners, the notifier writes the event byte to 101 | all the named pipes in the directory. 102 | Credit for this idea goes to Stefan Karrmann. 103 | .It 104 | To unsubscribe, a listener unlinks his named pipe from the directory. 105 | .El 106 | .Pp 107 | Note that in the s6 implementation of fifodirs, there are a few 108 | additional details: for instance, the named pipes created in a fifodir 109 | by a listener follow a strict naming convention, for efficiency and 110 | safety reasons. 111 | If you are using fifodirs, it is recommended that you use the provided 112 | C library functions or the 113 | .Ql s6-ftrig-* 114 | command line utilities instead of directly hacking into the fifodir 115 | internals. 116 | .Pp 117 | Fifodirs are created by, so they always originally have the same uid 118 | and gid as, their notifier. 119 | A notifier must be able to make his fifodir either publicly accessible 120 | (anyone can subscribe) or restricted (only a given group can 121 | subscribe). 122 | .Pp 123 | A publicly accessible fifodir must have rights 1733: 124 | .Bl -bullet -width x 125 | .It 126 | Anyone can create a fifo in that fifodir. 127 | .It 128 | Only the notifier can see all the subscribers' fifos. 129 | .It 130 | A listener can only delete its own fifo. 131 | .It 132 | A notifier can delete any fifo for cleaning purposes. 133 | .El 134 | .Pp 135 | A restricted fifodir must have the gid g of the group of allowed 136 | listeners and have rights 3730. 137 | Unless the notifier is root, it must be in the group of allowed 138 | listeners to be able to create such a fifodir. 139 | .Bl -bullet -width x 140 | .It 141 | Only members of g can create a fifo in that fifodir. 142 | .It 143 | Only the notifier can see all the subscribers' fifos. 144 | .It 145 | Fifos are always created with gid g. 146 | .It 147 | A listener can only delete its own fifo. 148 | .It 149 | A notifier can delete any fifo for cleaning purposes. 150 | .El 151 | .Pp 152 | A named pipe in a fifodir must always belong to its listener and have 153 | rights 0622: 154 | .Bl -bullet -width x 155 | .It 156 | Only this listener can read on the fifo. 157 | .It 158 | Anyone who has reading rights on the fifodir (i.e. only the notifier) 159 | can write to the fifo. 160 | .El 161 | .Pp 162 | The libftrig interface takes care of all the subtleties. 163 | .Sh SEE ALSO 164 | [1] 165 | .Lk https://skarnet.org/software/skalibs/libstddjb/djbunix.html 166 | .Pp 167 | This man page is ported from the authoritative documentation at: 168 | .Lk https://skarnet.org/software/s6/fifodir.html 169 | .Sh AUTHORS 170 | .An Laurent Bercot 171 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 172 | -------------------------------------------------------------------------------- /man7/s6-ftrigw.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIGW 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrigw 6 | .Nd API for notifiers, i.e. programs that want to regularly announce what they're doing 7 | .Sh DESCRIPTION 8 | Notifiers should create an 9 | .Xr s6-fifodir 7 10 | in a hardcoded place in the filesystem, and document its 11 | location. 12 | Listeners will then be able to subscribe to that 13 | .Xr s6-fifodir 7 , 14 | and receive the events. 15 | .Pp 16 | Check the 17 | .Pa s6/ftrigw.h 18 | header for the exact function prototypes. 19 | .Ss Creating a fifodir 20 | .Bd -literal -offset indent 21 | char const *path = "/var/lib/myservice/fifodir" ; 22 | gid_t gid = -1 ; 23 | int forceperms = 0 ; 24 | int r = ftrigw_fifodir_make(path, gid, forceperms) ; 25 | .Ed 26 | .Pp 27 | .Fn ftrigw_fifodir_make 28 | creates an 29 | .Xr s6-fifodir 7 30 | at the 31 | .Va path 32 | location. 33 | It returns 0, and sets errno, if an error occurs. 34 | It returns 1 if it succeeds. 35 | .Pp 36 | If an 37 | .Xr s6-fifodir 7 , 38 | owned by the user, already exists at 39 | .Va path , 40 | and 41 | .Va forceperms 42 | is zero, then 43 | .Fn ftrigw_fifodir_make 44 | immediately returns success. 45 | If 46 | .Va forceperms 47 | is nonzero, then it tries to adjust 48 | .Va path 49 | .Ap s 50 | permissions before returning. 51 | .Pp 52 | If 53 | .Va gid 54 | is negative, then 55 | .Va path 56 | is created 57 | .Dq public . 58 | Any listener will be able to subscribe to 59 | .Va path . 60 | If 61 | .Va gid 62 | is nonnegative, then 63 | .Va path 64 | is created 65 | .Dq private . 66 | Only processes belonging to group 67 | .Va gid 68 | will be able to subscribe to 69 | .Va path . 70 | .Ss Sending an event 71 | .Bd -literal -offset indent 72 | char event = 'a' ; 73 | r = ftrigw_notify(path, event) ; 74 | .Ed 75 | .Pp 76 | .Fn ftrigw_notify 77 | sends 78 | .Va event 79 | to all the processes that are currently subscribed to 80 | .Va path . 81 | It returns -1 if an error occurs, or the number of successfully 82 | notified processes. 83 | .Ss Cleaning up 84 | When stray KILL signals hit 85 | .Xr s6-ftrigrd 8 86 | processes, 87 | .Bl -enum -width x 88 | .It 89 | it's a sign of incorrect system administration, 90 | .It 91 | they can leave unused named pipes in the 92 | .Xr s6-fifodir 7 . 93 | .El 94 | .Pp 95 | It's the 96 | .Xr s6-fifodir 7 Ap 97 | s owner's job, i.e. the notifier's job, to periodically do some 98 | housecleaning and remove those unused pipes. 99 | .Bd -literal -offset indent 100 | r = ftrigw_clean(path) ; 101 | .Ed 102 | .Pp 103 | .Fn ftrigw_clean 104 | cleans 105 | .Va path . 106 | It returns 0, and sets errno, if it encounters an error. 107 | It returns 1 if it succeeds. 108 | .Sh SEE ALSO 109 | .Xr s6-accessrules 7 , 110 | .Xr s6-fdholder 7 , 111 | .Xr s6-ftrigr 7 , 112 | .Xr s6-libs6 7 , 113 | .Xr s6-s6lock 7 114 | .Pp 115 | This man page is ported from the authoritative documentation at: 116 | .Lk https://skarnet.org/software/s6/libs6/ftrigw.html 117 | .Sh AUTHORS 118 | .An Laurent Bercot 119 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 120 | -------------------------------------------------------------------------------- /man7/s6-instanced-service.7: -------------------------------------------------------------------------------- 1 | .Dd February 19, 2023 2 | .Dt S6-INSTANCED-SERVICE 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instanced-service 6 | .Nd dynamic instantiation 7 | .Sh DESCRIPTION 8 | An 9 | .Em instanced service 10 | is a parameterized service that you want to run several copies of, 11 | with only the parameter changing. 12 | Each copy of the service is called an 13 | .Em instance . 14 | .Pp 15 | With s6, an 16 | .Xr s6-service-directory 7 17 | can only handle one process at a time. 18 | So, if we want instanced services, there will have to be one service 19 | directory per instance, always. 20 | .Pp 21 | .Em Static instantiation 22 | means that the set of possible instances is finite and known in 23 | advance. 24 | With s6, it means that all the service directories for all possible 25 | instances are created, typically by a preprocessor, and instances are 26 | treated like regular services. 27 | .Pp 28 | .Em Dynamic instantiation 29 | means that instances are created on demand instead of preallocated. 30 | Starting with version 2.11.2.0, s6 provides a few tools to help users 31 | set up and manage dynamically instanced services. 32 | .Ss How to make a dynamically instanced service under s6 33 | .Bl -bullet -width x 34 | .It 35 | Write a template for a service directory that would run under 36 | .Xr s6-supervise 8 . 37 | The 38 | .Pa run 39 | script should take the name of the instance as its first argument; the 40 | .Pa finish 41 | script, if present, should take the name of the instance as its third 42 | argument. 43 | .It 44 | Call the 45 | .Xr s6-instance-maker 8 46 | program with this template as first argument, and a path 47 | .Pa dir 48 | as second argument. 49 | .Xr s6-instance-maker 8 50 | will create a service directory in 51 | .Pa dir . 52 | This is an offline tool: it does not interact with any currently 53 | active services or supervision trees. 54 | .It 55 | Supervise 56 | .Pa dir 57 | by adding it to your regular 58 | .Xr s6-scan-directory 7 . 59 | This will be your instanced service, but it's not running any instances yet. 60 | It is, instead, a nested supervision tree - the instanced service is an 61 | .Xr s6-svscan 8 62 | process that will supervise all the instances. 63 | .It 64 | Create and delete instances at will with the 65 | .Xr s6-instance-create 8 66 | and 67 | .Xr s6-instance-delete 8 68 | programs; you can list all the available instances with 69 | .Xr s6-instance-list 8 . 70 | These tools are 71 | .Em online : 72 | they work with live service directories, i.e. that are being supervised by 73 | .Xr s6-supervise 8 . 74 | .It 75 | Instances are regular supervised processes. 76 | You can control individual instances with 77 | .Xr s6-instance-control 8 , 78 | and check their status with 79 | .Xr s6-instance-status 8 . 80 | These tools are online as well. 81 | .El 82 | .Ss Internal workings 83 | This section is not normative; users should not rely on it. 84 | It is only here for informational purposes. 85 | .Bl -bullet -width x 86 | .It 87 | The service directory created by 88 | .Xr s6-instance-maker 8 89 | has three specifics subdirectories in it: 90 | .Pa instance 91 | and 92 | .Pa instances , 93 | which are initially empty, and 94 | .Pa template , 95 | storing the template service directory. 96 | .It 97 | When the service is active, there is an 98 | .Xr s6-svscan 8 99 | process running on 100 | .Pa instance . 101 | .It 102 | .Xr s6-instance-create 8 103 | makes a copy of 104 | .Pa template 105 | into 106 | .Pa instances/ Ns Ar name , 107 | and 108 | .Xr s6-svlink 8 Ns 109 | s 110 | .Pa instances/ Ns Ar name 111 | to 112 | .Pa instance . 113 | When it returns, there is an 114 | .Xr s6-supervise 8 115 | process running on 116 | .Pa instance/ Ns Ar name , 117 | and the instance may be up or not depending on the given options. 118 | .It 119 | .Xr s6-instance-control 8 120 | is syntactic sugar around 121 | .Xr s6-svc 8 122 | on 123 | .Pa instance/ Ns Ar name . 124 | .It 125 | .Xr s6-instance-status 8 126 | is syntactic sugar around 127 | .Xr s6-svstat 8 128 | on 129 | .Pa instance/ Ns Ar name . 130 | .It 131 | .Xr s6-instance-delete 8 132 | is syntactic sugar around 133 | .Xr s6-svunlink 8 134 | on 135 | .Pa instance/ Ns Ar name . 136 | .It 137 | .Xr s6-instance-list 8 138 | is roughly equivalent to 139 | .Ql ls -1 instance . 140 | .El 141 | .Ss Notes 142 | This implementation of dynamic instances may seem expensive: it 143 | creates one 144 | .Xr s6-svscan 8 145 | process per instanced service, and one 146 | .Xr s6-supervise 8 147 | process per instance. 148 | However, remember that these processes use very little private memory, 149 | so having additional copies of them is far less expensive than it 150 | looks. 151 | It's really a convenient way to implement the feature by reusing 152 | existing code. 153 | .Sh SEE ALSO 154 | .Xr s6-instance-control 8 , 155 | .Xr s6-instance-create 8 , 156 | .Xr s6-instance-delete 8 , 157 | .Xr s6-instance-list 8 , 158 | .Xr s6-instance-maker 8 , 159 | .Xr s6-instance-status 8 160 | .Sh AUTHORS 161 | .An Laurent Bercot 162 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 163 | -------------------------------------------------------------------------------- /man7/s6-libs6.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-LIBS6 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-libs6 6 | .Nd collection of utility C interfaces, used in the s6 executables 7 | .Sh DESCRIPTION 8 | .Ss Compiling 9 | Make sure the s6 headers, as well as the skalibs headers, are visible 10 | in your header search path. 11 | .Pp 12 | Use 13 | .Ql #include . 14 | .Ss Linking 15 | Make sure the s6 libraries, as well as the skalibs libraries, are 16 | visible in your library search path. 17 | .Pp 18 | Link against 19 | .Ql -ls6 20 | and 21 | .Ql -lskarnet . 22 | If you're using socket functions (which is the case with 23 | .Xr s6-ftrigr 7 , 24 | for instance), add 25 | .Ql `cat $sysdeps/socket.lib` 26 | to your command line. 27 | If you're using timed functions involving TAI timestamps (which is 28 | also the case with 29 | .Xr s6-ftrigr 7 , 30 | for instance), add 31 | .Ql `cat $sysdeps/sysclock.lib` . 32 | .Qq $sysdeps 33 | stands for your skalibs sysdeps directory. 34 | .Ss Programming 35 | The 36 | .Pa s6/s6.h 37 | header is actually a concatenation of other headers: libs6 is 38 | separated into several modules, each of them with its own header. 39 | .Bl -bullet -width x 40 | .It 41 | The 42 | .Pa s6/accessrules.h 43 | header provides functions to check credentials against configuration 44 | files. 45 | Refer to 46 | .Xr s6-accessrules 7 . 47 | .It 48 | The 49 | .Pa s6/ftrigr.h 50 | header provides functions to subscribe to 51 | .Xr s6-fifodir 7 Ns s 52 | and be notified of events. 53 | Refer to 54 | .Xr s6-ftrigr 7 . 55 | .It 56 | The 57 | .Pa s6/ftrigw.h 58 | header provides functions to manage 59 | .Xr s6-fifodir 7 Ns s 60 | and send notifications to them. 61 | Refer to 62 | .Xr s6-ftrigw 7 . 63 | .It 64 | The 65 | .Pa s6/s6lock.h 66 | header provides functions to acquire locks with a timeout. 67 | Refer to 68 | .Xr s6-s6lock 7 . 69 | .It 70 | The 71 | .Pa s6/s6-fdholder.h 72 | header provides functions to communicate with an 73 | .Xr s6-fdholderd 8 74 | server and exchange file descriptors with it. 75 | Refer to 76 | .Xr s6-fdholder 7 . 77 | .El 78 | .Sh SEE ALSO 79 | .Xr s6-accessrules 7 , 80 | .Xr s6-fdholder 7 , 81 | .Xr s6-ftrigr 7 , 82 | .Xr s6-ftrigw 7 , 83 | .Xr s6-s6lock 7 84 | .Pp 85 | This man page is ported from the authoritative documentation at: 86 | .Lk https://skarnet.org/software/s6/libs6/ 87 | .Sh AUTHORS 88 | .An Laurent Bercot 89 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 90 | -------------------------------------------------------------------------------- /man7/s6-local-service.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-LOCAL-SERVICE 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-local-service 6 | .Nd daemon that listens to incoming connections on a Unix domain socket 7 | .Sh DESCRIPTION 8 | Clients of the service are programs connecting to a Unix domain socket: the 9 | daemon performs operations on their behalf. 10 | .Pp 11 | The service is called 12 | .Em local 13 | because it is not accessible to clients from the network. 14 | .Pp 15 | A widely known example of a local service is the 16 | .Ql syslogd 17 | daemon. 18 | On most implementations, it listens to the 19 | .Pa /dev/log 20 | socket. 21 | Its clients connect to it and send their logs via the socket. 22 | The 23 | .Fn openlog 24 | function is just a wrapper arround the 25 | .Fn connect 26 | system call, the 27 | .Fn syslog 28 | function a wrapper around 29 | .Fn write , 30 | and so on. 31 | .Ss Benefits 32 | .Sy Privileges 33 | .Pp 34 | The most important benefit of a local service is that it permits 35 | .Sy controlled privilege gains without using setuid programs . 36 | The daemon is run as user S; a client running as user C and connecting 37 | to the daemon asks it to perform operations: those will be done as 38 | user S. 39 | .Pp 40 | Standard Unix permissions on the listening socket can be used to 41 | implement some basic access control: to restrict access to clients 42 | belonging to group G, change the socket to user S and group G, and 43 | give it 0420 permissions. 44 | This is functionally equivalent to the basic access control for setuid 45 | programs: a program having user S, group G and permissions 4750 will 46 | be executable by group G and run with S rights. 47 | .Pp 48 | But modern systems implement the 49 | .Fn getpeereid 50 | system call or library function. 51 | This function allows the server to know the client's credentials: so 52 | fine-grained access control is possible. 53 | On those systems, 54 | .Sy local services can do as much authentication as setuid programs, in a much more controlled environment . 55 | .Sy Fd-passing 56 | The most obvious difference between a local service and a network 57 | service is that a local service does not serve network clients. 58 | But local services have another nice perk: while network services 59 | usually only provide you with a single channel (a TCP or UDP socket) 60 | of communication between the client and the server, forcing you to 61 | multiplex your data into that channel, local services allow you to 62 | have as many communication channels as you want. 63 | .Pp 64 | (The SCTP transport layer provides a way for network services to use 65 | several communication channels. 66 | Unfortunately, it is not widely deployed yet, and a lot of network 67 | services still depend on TCP.) 68 | .Pp 69 | The 70 | .Em fd-passing 71 | mechanism is Unix domain socket black magic that allows one peer of 72 | the socket to send open file descriptors to the other peer. 73 | So, if the server opens a pipe and sends one end of this pipe to a 74 | client via this mechanism, there is effectively a socket 75 | .Em and 76 | a pipe between the client and the server. 77 | .Ss UCSPI 78 | The UCSPI[1] protocol is an easy way of abstracting clients and servers 79 | from the network. 80 | A server written as a UCSPI server, just as it can be run under inetd 81 | or 82 | .Xr s6-tcpserver 8 , 83 | can be run under 84 | .Xr s6-ipcserver 8 : 85 | choose a socket location and you have a local service. 86 | .Pp 87 | Fine-grained access control can be added by inserting 88 | .Xr s6-ipcserver-access 8 89 | in your server command line after 90 | .Xr s6-ipcserver 8 . 91 | .Pp 92 | A client written as an UCSPI client, i.e. assuming it has descriptor 6 93 | (resp. 7) open and reading from (resp. writing to) the server socket, 94 | can be run under 95 | .Xr s6-ipcclient 8 . 96 | .Ss Use in skarnet.org software 97 | skarnet.org libraries often use a separate process to handle 98 | asynchronicity and background work in a way that's invisible to the 99 | user. 100 | Among them are: 101 | .Bl -bullet -width x 102 | .It 103 | .Xr s6-ftrigrd 8 , 104 | managing the reception of notifications and only waking up the client 105 | process when the notification pattern matches a regular expression. 106 | .It 107 | .Xr s6lockd 8 , 108 | handling time-constrained lock acquisition on client behalf. 109 | .It 110 | skadnsd[2], 111 | performing asynchronous DNS queries and only waking up the client 112 | process when an answer arrives. 113 | .El 114 | .Pp 115 | Those processes are usually spawned from a client, via the 116 | corresponding 117 | .Ql *_startf* 118 | library call. 119 | But they can also be spawned from a 120 | .Xr s6-ipcserver 8 121 | program in a local service configuration. 122 | In both cases, they need an additional control channel to be passed 123 | from the server to the client: the main socket is used for synchronous 124 | commands from the client to the server and their answers, whereas the 125 | additional channel, which is now implemented as a socket as well (but 126 | created by the server on-demand and not bound to a local path), is 127 | used for asynchronous notifications from the server to the client. 128 | The fd-passing mechanism is used to transfer the additional channel 129 | from the server to the client. 130 | .Sh SEE ALSO 131 | .Xr s6-tcpserver 8 132 | [1] 133 | .Lk https://cr.yp.to/proto/ucspi.txt 134 | .Pp 135 | [2] 136 | .Lk https://skarnet.org/software/s6-dns/skadns/skadnsd.html 137 | .Pp 138 | This man page is ported from the authoritative documentation at: 139 | .Lk https://skarnet.org/software/s6/localservice.html 140 | .Sh AUTHORS 141 | .An Laurent Bercot 142 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 143 | -------------------------------------------------------------------------------- /man7/s6-scan-directory.7: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SCAN-DIRECTORY 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-scan-directory 6 | .Nd directory containing a list of service directories, or symbolic links pointing to service directories 7 | .Sh DESCRIPTION 8 | A 9 | .Em scan directory 10 | represents a list of services that are supposed to be 11 | supervised. 12 | Running 13 | .Xr s6-svscan 8 14 | on this scan directory launches a 15 | .Em supervision tree : 16 | every service listed in the scan directory will be supervised. 17 | .Pp 18 | There is normally only one scan directory per system, although nothing 19 | prevents a system administrator from having more. daemontools[1] 20 | traditionally uses 21 | .Pa /service , 22 | and runit[2] traditionally uses 23 | .Pa /etc/service . 24 | s6 does not care where your scan directory is, but I would advise 25 | .Pa /service 26 | for compatibility with daemontools. 27 | Depending on your installation, 28 | .Pa /service 29 | could be a symbolic link and point to a place either in a RAM 30 | filesystem or in 31 | .Pa /var . 32 | .Ss Where and how to build a scan directory 33 | Opinions and practices differ. 34 | .Pp 35 | It is generally accepted that the place where you store all your 36 | service directories (your 37 | .Dq service repository ) 38 | should not be used as a scan directory - for a simple reason: you 39 | might want to have service directories for more services than what you 40 | want to start at any given time. 41 | In other words, your scan directory will be a subset of your service 42 | repository, so you cannot just run 43 | .Xr s6-svscan 8 44 | on every service you have a service directory for. 45 | So, the first thing is to separate your service repository, which is 46 | just a storage place for all the services you might want to manage 47 | someday, and your scan directory, which is a directory representing 48 | all the services that you are currently managing. 49 | .Ss SERVICE REPOSITORY 50 | Where to store your service repository is purely a matter of personal 51 | preference. 52 | You just have to be aware that 53 | .Xr s6-supervise 8 54 | needs writable 55 | .Pa supervise 56 | and 57 | .Pa event 58 | subdirectories in a service directory it monitors. 59 | .Ss SCAN DIRECTORY 60 | Where and how to build your scan directory depends heavily on your 61 | boot system - and on your personal preference too. 62 | .Pp 63 | Standard daemontools[1] and runit[2] installations like to have a 64 | fixed scan directory containing symlinks to service directories 65 | located in the service repository. 66 | In other words, the service repository contains the real working 67 | copies of the service directories. 68 | This works, as long as: 69 | .Bl -bullet -width x 70 | .It 71 | It is possible to create writable 72 | .Pa supervise 73 | and 74 | .Pa event 75 | subdirectories in every managed service directory. 76 | This can be achieved for instance via symlinks, or by having the 77 | service repository stored on a writable filesystem. 78 | .It 79 | The scan program 80 | .Po 81 | .Xr s6-svscan 8 , 82 | svscan, 83 | .Xr runsvdir 8 ... 84 | .Pc 85 | is started late enough for all the necessary filesystems to be mounted. 86 | .El 87 | .Pp 88 | My own recommendation would be to have working copies of the service 89 | directories entirely separate from the service repository. 90 | The service repository can be safely stored on the root filesystem, 91 | and the needed directories copied to a RAM filesystem at boot 92 | time. 93 | The scan directory can be either the place where the working copies 94 | are written, or another directory containing symlinks to those working 95 | copies. (The latter is useful if you are using the 96 | .Fl t 97 | option to 98 | .Xr s6-svscan 8 99 | with a nonzero argument: copying a directory is not atomic, but making 100 | a symlink is, so there is no risk of your scanner finding a directory 101 | while it is being copied - which could result in 102 | .Xr s6-supervise 8 103 | getting the wrong information and not managing the service properly.) 104 | .Pp 105 | An example: 106 | .Bl -bullet -width x 107 | .It 108 | Have your service repository in 109 | .Pa /img/services , 110 | i.e. have service directories in 111 | .Pa /img/services/ftpd , 112 | .Pa /img/services/httpd , 113 | .Pa /img/services/sshd , 114 | etc. 115 | .It 116 | When booting, make 117 | .Pa /tmp 118 | a RAM filesystem, and create the directories 119 | .Pa /tmp/services 120 | and 121 | .Pa /tmp/service . 122 | .It 123 | Have 124 | .Xr s6-svscan 8 125 | run on 126 | .Pa /tmp/service , 127 | as early as possible in your boot sequence. 128 | This is possible whether you want to run 129 | .Xr s6-svscan 8 130 | as process 1[3] or not[4]. 131 | .It 132 | During the boot sequence, populate 133 | .Pa /tmp/services 134 | with copies of the service directories you need: for instance, 135 | .Bd -literal -offset indent 136 | cp -a /img/services/sshd /tmp/services/sshd 137 | cp -a /img/services/ftpd /tmp/services/ftpd 138 | etc. 139 | .Ed 140 | .It 141 | When you are ready to start a service, make a symlink in the 142 | .Pa /tmp/service 143 | scan directory pointing to the working copy of the 144 | .Xr s6-service-directory 7 145 | you need in 146 | .Pa /tmp/services , 147 | then notify 148 | .Xr s6-svscan 8 . 149 | For instance, to start ftpd and httpd together: 150 | .Bd -literal -offset indent 151 | ln -s ../services/ftpd /tmp/service 152 | ln -s ../services/httpd /tmp/service 153 | s6-svscanctl -a /tmp/service 154 | .Ed 155 | .El 156 | .Sh SEE ALSO 157 | .Xr s6-fifodir 7 , 158 | .Xr s6-service-directory 7 159 | .Pp 160 | [1] 161 | .Lk https://cr.yp.to/daemontools.html 162 | .Pp 163 | [2] 164 | .Lk http://smarden.org/runit/ 165 | .Pp 166 | [3] 167 | .Lk https://skarnet.org/software/s6/s6-svscan-1.html 168 | .Pp 169 | [4] 170 | .Lk https://skarnet.org/software/s6/s6-svscan-not-1.html 171 | .Pp 172 | This man page is ported from the authoritative documentation at: 173 | .Lk https://skarnet.org/software/s6/scandir.html 174 | .Sh AUTHORS 175 | .An Laurent Bercot 176 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 177 | -------------------------------------------------------------------------------- /man7/s6-socket-activation.7: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt S6-SOCKET-ACTIVATION 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-socket-activation 6 | .Nd performing socket activation with s6 7 | .Sh DESCRIPTION 8 | First, it's important to realize that you don't 9 | .Em need 10 | socket activation. 11 | It's a marketing word used by systemd advocates that mixes a couple 12 | useful architecture concepts and several horrible ideas, for a very 13 | minor speed benefit. 14 | Read [1] and [2] for details. 15 | .Bl -bullet -width x 16 | .It 17 | s6 18 | .Em will not 19 | help you implement super-servers in process 1, because doing so is bad 20 | engineering. 21 | However, it 22 | .Em will 23 | help you set up super-servers. 24 | The 25 | .Xr s6-ipcserver 8 26 | program, for Unix domain sockets, as well as the 27 | .Xr s6-tcpserver4 8 28 | and 29 | .Xr s6-tcpserver6 8 30 | programs, for TCP INET domain sockets 31 | .Po 32 | available in the s6-networking package[3] 33 | .Pc 34 | are super-servers you can use to your heart's content. 35 | They are even wrappers around simpler programs, and you can use their 36 | components in the way you choose: bind sockets, drop privileges, 37 | accept connections from clients, it's all about what you write in your 38 | command line. 39 | Super-servers are a good thing; using process 1 to act as a 40 | super-server is not. 41 | s6 provides you with the tools to get the good without the bad. 42 | .It 43 | s6 44 | .Em will not 45 | help you run all your services before their dependencies are met, 46 | because doing so is 47 | .Em very 48 | bad engineering. 49 | However, it 50 | .Em will 51 | provide you with: 52 | .Bl -bullet -width x 53 | .It 54 | a reliable logging infrastructure, that makes sure your services 55 | never lose logs: 56 | .Xr s6-log 8 , 57 | in conjunction with 58 | .Xr s6-supervise 8 59 | and 60 | .Xr s6-svscan 8 . 61 | .It 62 | ways to open your sockets and bind them as early as you want in your 63 | boot process, and make them accept client connections later: 64 | .Xr s6-ipcserver-socketbinder 8 , 65 | .Xr s6-tcpserver4-socketbinder 8 66 | and 67 | .Xr s6-tcpserver6-socketbinder 8 . 68 | .It 69 | a supervision infrastructure that can start as many services in 70 | parallel as you want: 71 | .Xr s6-supervise 8 72 | and 73 | .Xr s6-svscan 8 . 74 | .El 75 | .It 76 | s6 77 | .Em will not 78 | help you centralize all your socket information in process 1, because 79 | doing so is contrary to modularity and independence of services. 80 | However, s6 81 | .Em will 82 | provide you with a way to store your open sockets and retrieve them 83 | when you want, which it calls 84 | .Dq fd holding : 85 | .Xr s6-fdholder-daemon 8 . 86 | .El 87 | .Ss So, how do I open all my sockets first, store them, and dispatch them to daemons later? 88 | Again, it's not necessary to do that: you'll be fine, and quite 89 | speedy, just starting your daemons in their good time. 90 | You 91 | .Em will not 92 | reap any noticeable benefit from performing 93 | .Dq socket activation . 94 | But if you really want to: 95 | .Bl -enum -width x 96 | .It 97 | Make sure you have an early supervision infrastructure running. 98 | Ideally, you would make 99 | .Xr s6-svscan 8 100 | your process 1 . 101 | .It 102 | Start an early fd-holding service, e.g. 103 | .Xr s6-fdholder-daemon 8 . 104 | Let's say the fd-holding daemon is listening on socket 105 | .Pa /service/fdholder/s . 106 | .It 107 | For every Unix domain socket 108 | .Pa /my/socket 109 | you need to open, run: 110 | .Bd -literal 111 | s6-ipcserver-socketbinder /my/socket s6-fdholder-store /service/fdholder/s unix:/my/socket 112 | .Ed 113 | .Pp 114 | You can do the same with INET domain sockets. 115 | .It 116 | Proceed to your initialization. 117 | .It 118 | When you want to run a daemon 119 | .Ql myserverd 120 | that accepts clients connecting to 121 | .Pa /my/socket , 122 | run: 123 | .Bd -literal 124 | s6-fdholder-retrieve /service/fdholder/s unix:/my/socket myserverd 125 | .Ed 126 | .Pp 127 | .Ql myserverd 128 | will be executed with 129 | .Pa /my/socket 130 | as its standard input. 131 | .It 132 | The descriptors remain safely stored in the fd-holding daemon and you 133 | can retrieve them again whenever you want, for instance when your 134 | service crashes and is restarted. 135 | .El 136 | .Pp 137 | That is all there is to it. 138 | You don't have to use specific libraries or write complex unit files, 139 | you just need to understand how a command line works. 140 | This is Unix. 141 | .Sh SEE ALSO 142 | [1] 143 | .Lk https://skarnet.org/lists/supervision/0422.html 144 | .Pp 145 | [2] 146 | .Lk https://forums.gentoo.org/viewtopic-t-994548-postdays-0-postorder-asc-start-25.html#7581522 147 | .Pp 148 | [3] 149 | .Lk https://skarnet.org/software/s6-networking/ 150 | .Sh AUTHORS 151 | .An Laurent Bercot 152 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 153 | -------------------------------------------------------------------------------- /man7/s6-svscan-not-as-process-1.7: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt S6-SVSCAN-NOT-AS-PROCESS-1 7 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svscan-not-as-process-1 6 | .Nd running 7 | .Xr s6-svscan 8 8 | under another init process 9 | .Sh DESCRIPTION 10 | You can have a reliable supervision tree even if 11 | .Xr s6-svscan 8 12 | is not your process 1. 13 | The supervision tree just has to be 14 | .Em rooted 15 | in process 1: that means that your process 1 will have to supervise 16 | your 17 | .Xr s6-svscan 8 18 | process somehow. 19 | That way, if 20 | .Xr s6-svscan 8 21 | dies, it will be restarted, and your set of services will always be 22 | maintained. 23 | .Pp 24 | Be aware, though, that pipes between services and loggers are 25 | maintained by the 26 | .Xr s6-svscan 8 27 | process; if this process dies, the pipes will be closed and some logs 28 | may be lost. 29 | .Ss Logging the supervision tree's output 30 | .Xr s6-svscan 8 31 | and the various 32 | .Xr s6-supervise 8 33 | processes might produce error or warning messages; those messages are written to 34 | .Xr s6-svscan 8 Ap 35 | s stderr 36 | .Po 37 | which is inherited by the 38 | .Xr s6-supervise 8 39 | processes 40 | .Pc . 41 | To log these messages: 42 | .Bl -bullet -width x 43 | .It 44 | You can use your init system's logging tools, and make your init 45 | system launch 46 | .Xr s6-svscan 8 47 | as is; its stderr should already be taken care of by the logging 48 | tools. 49 | .It 50 | You can use a trick similar to the 51 | .Xr s6-svscan-as-process-1 7 52 | process 1 output logging trick so the supervision tree's messages are 53 | logged via a service that's maintained by the supervision tree itself. 54 | Then your init system should not launch 55 | .Xr s6-svscan 8 56 | directly, but a wrapper script that performs the proper redirections. 57 | The 58 | .Pa examples/s6-svscanboot 59 | file in the s6 distribution gives an example of such a script. 60 | Make sure that your initial 61 | .Xr s6-scan-directory 7 62 | contains an 63 | .Xr s6-service-directory 7 64 | for your initial logging service, that must read on the logging FIFO. 65 | .El 66 | .Pp 67 | In some of the following examples, we'll assume that 68 | .Pa /command/s6-svscanboot 69 | is the name of the script you are using to start 70 | .Xr s6-svscan 8 . 71 | We will also assume that all of the s6 executables are available 72 | through the 73 | .Pa /command 74 | path. 75 | Adjust this accordingly. 76 | .Ss System V init 77 | Put an appropriate line in your 78 | .Pa /etc/inittab 79 | file, then reload this config file with 80 | .Ql telinit q : 81 | .Bd -literal 82 | SV:123456:respawn:/command/s6-svscanboot 83 | .Ed 84 | .Ss Upstart 85 | Put an appropriate configuration file in the 86 | .Pa /etc/init 87 | folder, for instance 88 | .Pa /etc/init/s6-svscan.conf , 89 | then start the service with 90 | .Ql start s6-svscan : 91 | .Bd -literal 92 | # s6-svscan 93 | start on runlevel [2345] 94 | stop on runlevel [!2345] 95 | 96 | oom never 97 | respawn 98 | exec /command/s6-svscanboot 99 | .Ed 100 | .Ss systemd 101 | Put an appropriate unit file in the 102 | .Pa /etc/systemd/system 103 | folder, for instance 104 | .Pa /etc/systemd/system/s6.service . 105 | It will be picked up by systemd at boot time: 106 | .Bd -literal 107 | [Unit] 108 | Description=s6 supervision tree 109 | Documentation=https://skarnet.org/software/s6/ 110 | 111 | [Install] 112 | WantedBy=multi-user.target 113 | 114 | [Service] 115 | Type=simple 116 | ExecStart=/command/s6-svscan /service 117 | ExecStop=/command/s6-svscanctl -t /service 118 | ExecReload=/command/s6-svscanctl -an /service 119 | Restart=always 120 | RestartSec=1 121 | .Ed 122 | .Pp 123 | Please note that, among other things, systemd performs process 124 | supervision, so depending on the level of integration with your 125 | distribution that you wish to achieve, you may be better off using 126 | systemd to directly manage your daemons. 127 | Please also note that systemd is a terrible piece of software 128 | engineering[1], and if at all possible, you should try and switch to a 129 | distribution that does not use it. 130 | .Ss BSD init 131 | Put an appropriate line in your 132 | .Pa /etc/ttys 133 | file, then reload this file with 134 | .Ql kill -s HUP 1 : 135 | .Bd -literal 136 | sv /command/s6-svscanboot "" on 137 | .Ed 138 | .Ss MacOS launchd 139 | Like systemd, launchd comes with its own way of supervising 140 | services[2]; if you are a launchd user, you probably do not need s6. 141 | .Sh SEE ALSO 142 | [1] 143 | .Lk https://skarnet.org/software/systemd.html 144 | .Pp 145 | [2] 146 | .Lk https://developer.apple.com/library/mac/documentation/macosx/conceptual/bpsystemstartup/chapters/CreatingLaunchdJobs.html 147 | .Sh AUTHORS 148 | .An Laurent Bercot 149 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 150 | -------------------------------------------------------------------------------- /man8/s6-accessrules-cdb-from-fs.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-ACCESSRULES-CDB-FROM-FS 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-accessrules-cdb-from-fs 6 | .Nd compile a directory containing a ruleset suitable for 7 | .Xr s6-ipcserver-access 8 8 | or 9 | .Xr s6-tcpserver-access 8 10 | into a CDB[1] file 11 | .Sh SYNOPSIS 12 | .Nm 13 | .Ar cdbfile 14 | .Ar dir 15 | .Sh DESCRIPTION 16 | .Nm 17 | compiles the 18 | .Ar dir 19 | directory containing a ruleset into a CDB[1] file 20 | .Ar cdbfile 21 | then exits 0. 22 | .Ss Ruleset directory format 23 | To be understood by 24 | .Nm , 25 | .Xr s6-ipcserver-access 8 , 26 | or 27 | .Xr s6-tcpserver-access 8 , 28 | .Ar dir 29 | must have a specific format. 30 | .Pp 31 | .Ar dir 32 | contains a series of directories: 33 | .Bl -bullet -width x 34 | .It 35 | .Pa ip4 36 | for rules on IPv4 addresses. 37 | .It 38 | .Pa ip6 39 | for rules on IPv6 addresses. 40 | .It 41 | .Pa reversedns 42 | for rules on host names. 43 | .It 44 | .Pa uid 45 | for rules on user IDs. 46 | .It 47 | .Pa gid 48 | for rules on group IDs. 49 | .El 50 | .Pp 51 | Depending on the application, other directories can appear in 52 | .Ar dir 53 | and be compiled into 54 | .Ar cdbfile , 55 | but 56 | .Xr s6-tcpserver-access 8 57 | only uses the first three, and 58 | .Xr s6-ipcserver-access 8 59 | only uses the last two. 60 | .Pp 61 | Each of those directories contains a set of rules. 62 | A rule is a subdirectory named after the set of keys it matches, and 63 | containing actions that will be executed if the rule is the first 64 | matching rule for the tested key. 65 | .Pp 66 | The syntax for the rule name is dependent on the nature of keys, and 67 | fully documented in 68 | .Xr s6-accessrules 7 . 69 | For instance, a subdirectory named 192.168.0.0_27 in the 70 | .Pa ip4 71 | directory will match every IPv4 address in the 192.168.0.0/27 network 72 | that does not match a more precise rule. 73 | .Pp 74 | The syntax for the actions, however, is the same for every type of 75 | key. 76 | A rule subdirectory can contain the following elements: 77 | .Bl -bullet -width x 78 | .It 79 | A file (that can be empty) named 80 | .Pa allow . 81 | If such a file exists, a key matching this rule will be immediately 82 | accepted. 83 | .It 84 | A file (that can be empty) named 85 | .Pa deny . 86 | If such a file exists and no 87 | .Pa allow 88 | file exists, a key matching this rule will be immediately denied. 89 | .It 90 | A subdirectory named 91 | .Pa env . 92 | If such a directory exists along with an 93 | .Pa allow 94 | file, then its contents represent environment modifications that will 95 | be applied after accepting the connection and before executing the 96 | next program in the chain, as if the 97 | .Xr s6-envdir 8 98 | program, without options, was applied to 99 | .Pa env . 100 | .Pa env 101 | has exactly the same format as a directory suitable for 102 | .Xr s6-envdir 8 ; 103 | however, if the modifications take up more than 4096 bytes when 104 | compiled into 105 | .Ar cdbfile , 106 | then 107 | .Nm 108 | will complain and exit 100. 109 | .It 110 | A file named 111 | .Pa exec . 112 | If such a file exists along with an 113 | .Pa allow 114 | file, then its contents represent a command line that, interpreted by 115 | the 116 | .Xr execlineb 1 117 | launcher, will be executed after accepting the connection, totally 118 | bypassing the original command line. 119 | .Nm 120 | truncates the 121 | .Pa exec 122 | file to 4096 bytes max when embedding it into 123 | .Ar cdbfile , 124 | so make sure it is not larger than that. 125 | .El 126 | .Pp 127 | .Ar cdbfile 128 | can exist prior to, and during, the compilation, which actually works 129 | in a temporary file in the same directory as 130 | .Ar cdbfile 131 | and performs an atomic replacement when it is done. 132 | So it is not necessary to interrupt a running service during the 133 | compilation. 134 | .Pp 135 | If 136 | .Nm 137 | fails at some point, the temporary file is removed. 138 | However, this doesn't happen if 139 | .Nm 140 | is interrupted by a signal. 141 | .Pp 142 | After the program successfully completes, if 143 | .Ar dir 144 | was a suitable candidate for the 145 | .Fl i 146 | option of 147 | .Xr s6-ipcserver-access 8 148 | or 149 | .Xr s6-tcpserver-access 8 , 150 | then 151 | .Ar cdbfile 152 | will be a suitable candidate for the 153 | .Fl x 154 | option of the same program, implementing the same ruleset. 155 | .Pp 156 | .Ar cdbfile 157 | can be decompiled by the 158 | .Xr s6-accessrules-fs-from-cdb 8 159 | program. 160 | .Sh SEE ALSO 161 | .Xr execlineb 1 , 162 | .Xr s6-accessrules-fs-from-cdb 8 , 163 | .Xr s6-connlimit 8 , 164 | .Xr s6-ioconnect 8 , 165 | .Xr s6-ipcclient 8 , 166 | .Xr s6-ipcserver 8 , 167 | .Xr s6-ipcserver-access 8 , 168 | .Xr s6-ipcserver-socketbinder 8 , 169 | .Xr s6-ipcserverd 8 , 170 | .Xr s6-tcpserver-access 8 171 | .Pp 172 | [1] 173 | .Lk https://en.wikipedia.org/wiki/Cdb_(software) 174 | .Pp 175 | This man page is ported from the authoritative documentation at: 176 | .Lk https://skarnet.org/software/s6/s6-accessrules-cdb-from-fs.html 177 | .Sh AUTHORS 178 | .An Laurent Bercot 179 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 180 | -------------------------------------------------------------------------------- /man8/s6-accessrules-fs-from-cdb.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-ACCESSRULES-FS-FROM-CDB 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-accessrules-fs-from-cdb 6 | .Nd decompile a CDB[1] database containing a ruleset suitable for 7 | .Xr s6-ipcserver-access 8 8 | or 9 | .Xr s6-tcpserver-access 8 10 | and that has been compiled with 11 | .Xr s6-accessrules-cdb-from-fs 8 12 | .Sh SYNOPSIS 13 | .Nm 14 | .Ar dir 15 | .Ar cdbfile 16 | .Sh DESCRIPTION 17 | .Nm 18 | decompiles the CDB[1] file 19 | .Ar cdbfile 20 | into the directory 21 | .Ar dir , 22 | then exits 0. 23 | .Pp 24 | .Ar dir 25 | must not exist prior to the decompilation. 26 | .Pp 27 | .Ar dir 28 | must be considered a work in progress as long as 29 | .Nm 30 | is running. 31 | It is only safe to use 32 | .Ar dir 33 | as a ruleset once the program has exited. 34 | .Pp 35 | If 36 | .Nm 37 | fails at some point, the partial arborescence at 38 | .Ar dir 39 | is removed. 40 | However, this doesn't happen if 41 | .Nm 42 | is interrupted by a signal. 43 | .Pp 44 | After the program successfully completes, if 45 | .Ar cdbfile 46 | was a suitable candidate for the 47 | .Fl x 48 | option of 49 | .Xr s6-ipcserver-access 8 50 | or 51 | .Xr s6-tcpserver-access 8 , 52 | then 53 | .Ar dir 54 | will be a suitable candidate for the 55 | .Fl i 56 | option of the same program, implementing the same ruleset. 57 | .Sh SEE ALSO 58 | .Xr s6-accessrules-cdb-from-fs 8 , 59 | .Xr s6-connlimit 8 , 60 | .Xr s6-ioconnect 8 , 61 | .Xr s6-ipcclient 8 , 62 | .Xr s6-ipcserver 8 , 63 | .Xr s6-ipcserver-access 8 , 64 | .Xr s6-ipcserver-socketbinder 8 , 65 | .Xr s6-ipcserverd 8 , 66 | .Xr s6-tcpserver-access 8 67 | .Pp 68 | [1] 69 | .Lk https://en.wikipedia.org/wiki/Cdb_(software) 70 | .Pp 71 | This man page is ported from the authoritative documentation at: 72 | .Lk https://skarnet.org/software/s6/s6-accessrules-fs-from-cdb.html 73 | .Sh AUTHORS 74 | .An Laurent Bercot 75 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 76 | -------------------------------------------------------------------------------- /man8/s6-applyuidgid.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-APPLYUIDGID 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-applyuidgid 6 | .Nd execute a program with reduced privileges 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl z 10 | .Op Fl u Ar uid 11 | .Op Fl g Ar gid 12 | .Op Fl G Ar gidlist 13 | .Op Fl U 14 | .Ar prog... 15 | .Sh DESCRIPTION 16 | .Nm 17 | sets its uid, gid and supplementary group list to the values given, 18 | then executes into 19 | .Ar prog . 20 | .Nm 21 | can only be run as root. 22 | Its main use is to drop root privileges before starting a daemon. 23 | .Nm 24 | is a more generic version of 25 | .Xr s6-setuidgid 8 . 26 | It is used as a command line building block by some programs that 27 | rewrite their command line, such as 28 | .Xr s6-tcpserver 8 . 29 | .Sh OPTIONS 30 | .Bl -tag -width x 31 | .It Fl u Ar uid 32 | Set the process' user ID to 33 | .Ar uid . 34 | .It Fl g Ar gid 35 | Set the process' group ID to 36 | .Ar gid . 37 | .It Fl G Ar gidlist 38 | Set the process' supplementary group list to 39 | .Ar gidlist , 40 | which must be given as a comma-separated list of numeric GIDs, without 41 | spaces. 42 | .It Fl U 43 | Set the process' user ID, group ID and supplementary group list to the 44 | values of the 45 | .Ev UID , 46 | .Ev GID 47 | and 48 | .Ev GIDLIST 49 | environment variables. 50 | If a 51 | .Fl u , 52 | .Fl g 53 | or 54 | .Fl G 55 | option is given after 56 | .Fl U , 57 | the command line value overrides the environment variable. 58 | .It Fl z 59 | Unexport. 60 | The 61 | .Ev UID , 62 | .Ev GID 63 | and 64 | .Ev GIDLIST 65 | variables will be removed from the process environment. 66 | .El 67 | .Sh SEE ALSO 68 | .Xr s6-envdir 8 , 69 | .Xr s6-envuidgid 8 , 70 | .Xr s6-fghack 8 , 71 | .Xr s6-setsid 8 , 72 | .Xr s6-setuidgid 8 , 73 | .Xr s6-softlimit 8 , 74 | .Xr s6-tai64n 8 , 75 | .Xr s6-tai64nlocal 8 , 76 | .Xr s6-tcpserver 8 77 | .Pp 78 | This man page is ported from the authoritative documentation at: 79 | .Lk https://skarnet.org/software/s6/s6-applyuidgid.html 80 | .Sh AUTHORS 81 | .An Laurent Bercot 82 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 83 | -------------------------------------------------------------------------------- /man8/s6-cleanfifodir.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-CLEANFIFODIR 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-cleanfifodir 6 | .Nd clean up an 7 | .Xr s6-fifodir 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Ar fifodir 11 | .Sh DESCRIPTION 12 | .Nm 13 | cleans up 14 | .Ar fifodir , 15 | that must belong to the current user. 16 | That means it removes all stale FIFOs in 17 | .Ar fifodir . 18 | .Pp 19 | In normal use, it is not necessary to call 20 | .Nm . 21 | However, stale FIFOs can be left by 22 | .Xr s6-ftrigrd 8 23 | processes that were violently killed, so it's good practice to 24 | regularly clean up fifodirs. 25 | .Sh SEE ALSO 26 | .Xr s6-ftrig-listen 8 , 27 | .Xr s6-ftrig-listen1 8 , 28 | .Xr s6-ftrig-notify 8 , 29 | .Xr s6-ftrig-wait 8 , 30 | .Xr s6-ftrigrd 8 , 31 | .Xr s6-mkfifodir 8 32 | .Pp 33 | This man page is ported from the authoritative documentation at: 34 | .Lk https://skarnet.org/software/s6/s6-cleanfifodir.html 35 | .Sh AUTHORS 36 | .An Laurent Bercot 37 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 38 | -------------------------------------------------------------------------------- /man8/s6-connlimit.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-CONNLIMIT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-connlimit 6 | .Nd 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 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar prog... 10 | .Sh DESCRIPTION 11 | .Nm 12 | reads its environment for the 13 | .Ev PROTO 14 | environment variable, and then for 15 | .Ev ${PROTO}CONNNUM 16 | and 17 | .Ev ${PROTO}CONNMAX , 18 | which must contain integers. 19 | .Pp 20 | If the value of 21 | .Ev ${PROTO}CONNNUM 22 | is superior or equal to the value of 23 | .Ev ${PROTO}CONNMAX , 24 | .Nm 25 | exits 1 with an error message. 26 | .Pp 27 | Else it execs into 28 | .Ar prog... . 29 | .Pp 30 | If 31 | .Ev ${PROTO}CONNMAX 32 | is unset, 33 | .Nm 34 | directly execs into 35 | .Ar prog... 36 | without performing any check: no maximum number of connections has 37 | been defined. 38 | .Pp 39 | The 40 | .Xr s6-tcpserver4 8 41 | and 42 | .Xr s6-tcpserver6 8 43 | programs define the 44 | .Ev PROTO 45 | environment variable to 46 | .Dq TCP , 47 | and spawn every child server with the 48 | .Ev TCPCONNNUM 49 | environment variable set to the number of connections from the same IP 50 | address. 51 | The 52 | .Xr s6-tcpserver-access 8 53 | program can set environment variables depending on the client's IP 54 | address. 55 | If the 56 | s6-tcpserver-access 57 | database is configured to set the 58 | .Ev TCPCONNMAX 59 | environment variable for a given set of IP addresses, and 60 | s6-tcpserver-access 61 | execs into 62 | .Nm , 63 | then 64 | .Nm 65 | will drop connections if there already are 66 | .Ev ${TCPCONNMAX} 67 | connections from the same client IP address. 68 | .Pp 69 | The 70 | .Xr s6-ipcserver 8 71 | and 72 | .Xr s6-ipcserver-access 8 73 | programs can be used the same way, with 74 | .Dq IPC 75 | instead of 76 | .Dq TCP , 77 | to limit the number of client connections by UID. 78 | .Pp 79 | The 80 | .Nm 81 | utility was once part of the s6-networking[1] suite, and is mostly useful 82 | with TCP connections, which is why the examples here involve TCP. 83 | Nevertheless, it can be used with connections across Unix domain 84 | sockets, and that is why it has been moved to the s6 package. 85 | .Sh EXAMPLES 86 | The following command line: 87 | .Bd -literal -offset indent 88 | s6-tcpserver4 -v2 -c1000 -C40 1.2.3.4 80 \ 89 | s6-tcpserver-access -v2 -RHl0 -i dir \ 90 | s6-connlimit \ 91 | prog... 92 | .Ed 93 | .Pp 94 | will run a server listening to IPv4 address 1.2.3.4, on port 80, 95 | serving up to 1000 concurrent connections, and up to 40 concurrent 96 | connections from the same IP address, no matter what the IP 97 | address. 98 | For every client connection, it will look up the database set up in 99 | .Ql dir ; 100 | if the connection is accepted, it will run 101 | .Ql prog... . 102 | .Pp 103 | If the 104 | .Pa dir/ip4/5.6.7.8_32/env/TCPCONNMAX 105 | file exists and contains the string 30, then at most 30 concurrent 106 | connections from 5.6.7.8 will execute 107 | .Ql prog... , 108 | instead of the default of 40. 109 | .Sh SEE ALSO 110 | .Xr s6-accessrules-cdb-from-fs 8 , 111 | .Xr s6-accessrules-fs-from-cdb 8 , 112 | .Xr s6-ioconnect 8 , 113 | .Xr s6-ipcclient 8 , 114 | .Xr s6-ipcserver 8 , 115 | .Xr s6-ipcserver-access 8 , 116 | .Xr s6-ipcserver-socketbinder 8 , 117 | .Xr s6-ipcserverd 8 , 118 | .Xr s6-tcpserver-access 8 , 119 | .Xr s6-tcpserver4 8 , 120 | .Xr s6-tcpserver6 8 121 | .Pp 122 | [1] 123 | .Lk https://skarnet.org/software/s6-networking/ 124 | .Pp 125 | This man page is ported from the authoritative documentation at: 126 | .Lk https://skarnet.org/software/s6/s6-connlimit.html 127 | .Sh AUTHORS 128 | .An Laurent Bercot 129 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 130 | -------------------------------------------------------------------------------- /man8/s6-envdir.8: -------------------------------------------------------------------------------- 1 | .Dd March 13, 2022 2 | .Dt S6-ENVDIR 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-envdir 6 | .Nd change environment, then execute into another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl I | i 10 | .Op Fl n 11 | .Op Fl f 12 | .Op Fl L 13 | .Op Fl c Ar nullis 14 | .Ar dir 15 | .Ar prog... 16 | .Sh DESCRIPTION 17 | .Nm 18 | reads files in 19 | .Ar dir . 20 | For every file 21 | .Em f 22 | in 23 | .Ar dir , 24 | that does not begin with a dot and does not contain the 25 | .Ql = 26 | character: 27 | .Bl -bullet -width x 28 | .It 29 | If 30 | .Em f 31 | is empty, remove a variable named 32 | .Ev f 33 | from the environment, if any. 34 | .It 35 | Else add a variable named 36 | .Ev f 37 | to the environment (or replace 38 | .Ev f 39 | if it already exists) with the first line of the contents of file 40 | .Pa f 41 | as value. 42 | Spaces and tabs at the end of this line are removed, as well as any 43 | trailing newline; null characters in this line are changed to newlines 44 | in the environment variable. 45 | .El 46 | .Pp 47 | .Nm 48 | without options behaves exactly like envdir[1]. 49 | .Sh OPTIONS 50 | .Bl -tag -width x 51 | .It Fl i 52 | Strict. 53 | If 54 | .Ar dir 55 | does not exist, exit 111 with an error message. 56 | This is the default. 57 | .It Fl I 58 | Loose. 59 | If 60 | .Ar dir 61 | does not exist, exec into 62 | .Ar prog 63 | without modifying the environment first. 64 | .It Fl f 65 | Verbatim mode. 66 | All the file is given as the value of the environment variable, 67 | including newlines (except the last one if the 68 | .Fl n 69 | option is not given). 70 | Null characters are still translated. 71 | .It Fl n 72 | Do not chomp. 73 | If the 74 | .Fl f 75 | option is given and the file ends with a newline, keep that last 76 | newline in the value. 77 | If the 78 | .Fl f 79 | option is not given, keep the trailing blanks at the end of the first 80 | line (but not the ending newline). 81 | .It Fl L 82 | Do not clamp. 83 | With this option, 84 | .Nm 85 | will process the whole first line of each file (if the 86 | .Fl f 87 | option hasn't been given) or read each file entirely (if the 88 | .Fl f 89 | option has been given), even if it means adding huge variables to the 90 | environment. 91 | Without this option, 92 | .Nm 93 | only reads the first 4096 bytes of each file. 94 | .It Fl c Ar nullis 95 | Replace null characters with the first character of 96 | .Ar nullis 97 | instead of a newline. 98 | .El 99 | .Sh SEE ALSO 100 | .Xr s6-applyuidgid 8 , 101 | .Xr s6-envuidgid 8 , 102 | .Xr s6-fghack 8 , 103 | .Xr s6-setsid 8 , 104 | .Xr s6-setuidgid 8 , 105 | .Xr s6-softlimit 8 , 106 | .Xr s6-tai64n 8 , 107 | .Xr s6-tai64nlocal 8 108 | .Pp 109 | [1] 110 | .Lk https://cr.yp.to/daemontools/envdir.html 111 | .Pp 112 | This man page is ported from the authoritative documentation at: 113 | .Lk https://skarnet.org/software/s6/s6-envdir.html 114 | .Sh AUTHORS 115 | .An Laurent Bercot 116 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 117 | -------------------------------------------------------------------------------- /man8/s6-envuidgid.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-ENVUIDGID 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-envuidgid 6 | .Nd potentially set the 7 | .Ev UID , 8 | .Ev GID 9 | and 10 | .Ev GIDLIST 11 | environment variables according to the options and arguments it is 12 | given, then execute into another program 13 | .Sh SYNOPSIS 14 | .Nm 15 | .Op Fl u | g | B 16 | .Op Fl n 17 | .Op Fl i | D Ar uid : Ns Ar gid : Ns Ar gidlist 18 | .Ar account 19 | .Ar prog... 20 | .Sh DESCRIPTION 21 | .Nm 22 | looks 23 | .Ar account 24 | up by name in the account database. 25 | .Pp 26 | It sets the UID environment variable to 27 | .Ar account Ap 28 | s uid, and the GID environment variable to 29 | .Ar account Ap 30 | s gid. 31 | .Pp 32 | It also sets the 33 | .Ev GIDLIST 34 | environment variable to a comma-separated list of supplementary group 35 | ids 36 | .Ar account 37 | is a member of according to the group database. (If 38 | .Ar account 39 | doesn't belong to any other group than its primary group, 40 | .Ev GIDLIST 41 | is still set, but empty.) 42 | .Pp 43 | Then it executes into 44 | .Ar prog... . 45 | .Pp 46 | .Nm 47 | without options behaves like envuidgid[1], except that the exit code is 1 if 48 | .Ar account 49 | doesn't exist, and it also exports supplementary groups. 50 | .Pp 51 | .Nm 52 | is useful when running a program that must start as root but can drop 53 | its privileges later. 54 | Such a program can read its new uid/gid/groups info from the 55 | .Ev UID , 56 | .Ev GID 57 | and 58 | .Ev GIDLIST 59 | environment variables. 60 | Super-servers such as 61 | .Xr s6-tcpserver4 8 62 | make use of this. 63 | .Sh OPTIONS 64 | .Bl -tag -width x 65 | .It Fl u 66 | User. 67 | .Ar account 68 | will be interpreted as a user name; the 69 | .Ev UID 70 | environment variable will be set to its numerical value, and the 71 | .Ev GID 72 | and 73 | .Ev GIDLIST 74 | variables will not be touched. 75 | .It Fl g 76 | Group. 77 | .Ar account 78 | will be interpreted as a group name instead of a user name; the 79 | .Ev GID 80 | environment variable will be set to its numerical value, and the 81 | .Ev UID 82 | and 83 | .Ev GIDLIST 84 | variables will not be touched. 85 | .It Fl B 86 | Both user and group. 87 | .Ar account 88 | will be interpreted as 89 | .Sm off 90 | .So 91 | .Em user : 92 | .Em group 93 | .Sc . 94 | .Sm on 95 | The 96 | .Ev GIDLIST 97 | variable will not be touched. 98 | If 99 | .Em user 100 | does not exist, the 101 | .Ev UID 102 | variable will be set to 0 unless a better default is provided with the 103 | .Fl D 104 | option. 105 | If 106 | .Em group 107 | does not exist, the 108 | .Ev GID 109 | variable will be set to 0 unless a better default is provided with the 110 | .Fl D 111 | option. 112 | .It Fl n 113 | Numerical fallback. 114 | If 115 | .Ar account 116 | cannot be found in the user or group database, try to interpret the 117 | given values literally. 118 | For instance, 119 | .Ql s6-envuidgid -B root:42 120 | will fail if there's no group named 121 | .Ql 42 122 | in the group database, but 123 | .Ql s6-envuidgid -nB root:42 124 | will set 125 | .Ev UID 126 | to 0 and 127 | .Ev GID 128 | to 42. 129 | .It Fl i 130 | Insist. 131 | If 132 | .Ar account 133 | is unknown, exit 1 with an error message. 134 | This is the default. 135 | .It Fl D Ar uid : Ns Ar gid : Ns Ar gidlist 136 | If 137 | .Ar account 138 | is unknown, use 139 | .Ar uid , 140 | .Ar gid 141 | and 142 | .Ar gidlist 143 | as the values for 144 | .Ev UID , 145 | .Ev GID 146 | and 147 | .Ev GIDLIST . 148 | .El 149 | .Sh SEE ALSO 150 | .Xr s6-applyuidgid 8 , 151 | .Xr s6-envdir 8 , 152 | .Xr s6-fghack 8 , 153 | .Xr s6-setsid 8 , 154 | .Xr s6-setuidgid 8 , 155 | .Xr s6-softlimit 8 , 156 | .Xr s6-tai64n 8 , 157 | .Xr s6-tai64nlocal 8 , 158 | .Xr s6-tcpserver4 8 159 | .Pp 160 | [1] 161 | .Lk https://cr.yp.to/daemontools/envuidgid.html 162 | .Pp 163 | This man page is ported from the authoritative documentation at: 164 | .Lk https://skarnet.org/software/s6/s6-envuidgid.html 165 | .Sh AUTHORS 166 | .An Laurent Bercot 167 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 168 | -------------------------------------------------------------------------------- /man8/s6-fdholder-daemon.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-DAEMON 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-daemon 6 | .Nd fd-holding daemon 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl 1 10 | .Op Fl v Ar verbosity 11 | .Op Fl d | D 12 | .Op Fl c Ar maxconn 13 | .Op Fl n Ar maxfds 14 | .Op Fl b Ar backlog 15 | .Op Fl G Ar gidlist 16 | .Op Fl g Ar gid 17 | .Op Fl u Ar uid 18 | .Op Fl U 19 | .Op Fl t Ar clienttimeout 20 | .Op Fl T Ar lameducktimeout 21 | .Op Fl i Ar rulesdir | Fl x Ar rulesfile 22 | .Ar path 23 | .Sh DESCRIPTION 24 | .Nm 25 | listens on a Unix domain socket, then accepts client connections; it 26 | stores file descriptors on behalf of clients, along with an identifier 27 | for every file descriptor stored, and possibly an expiration date 28 | (after which the file descriptor will be forgotten). 29 | It also allows clients to retrieve a file descriptor by its 30 | identifier. 31 | .Pp 32 | .Nm 33 | parses the options and arguments it is given, and builds a new command 34 | line with them. 35 | It then executes into that new command line. 36 | .Pp 37 | The first program 38 | .Nm 39 | executes into is 40 | .Xr s6-ipcserver-socketbinder 8 . 41 | It will create and bind a Unix domain socket to 42 | .Ar path , 43 | then execute into the rest of the command line. 44 | .Pp 45 | If a privilege-dropping operation has been requested, the program that 46 | .Xr s6-ipcserver-socketbinder 8 47 | executes into is 48 | .Xr s6-applyuidgid 8 . 49 | It will drop root privileges, then execute into the rest of the 50 | command line. 51 | .Pp 52 | The last program in the chain is 53 | .Xr s6-fdholderd 8 . 54 | It is executed into by 55 | .Xr s6-applyuidgid 8 , 56 | or directly by 57 | .Xr s6-ipcserver-socketbinder 8 58 | if no privilege-dropping operation has been requested. 59 | .Xr s6-fdholderd 8 60 | is the long-lived process, the daemon itself, performing fd holding 61 | and accepting connections from clients. 62 | .Pp 63 | .Nm 64 | does not interpret its options itself. 65 | It just dispatches them to the appropriate program on the command line 66 | that it builds. 67 | .Pp 68 | From the user's point of view, 69 | .Nm 70 | behaves like a long-lived process, even if the long-lived process 71 | itself is called 72 | .Xr s6-fdholderd 8 . 73 | Every operational detail of 74 | .Xr s6-fdholderd 8 75 | applies to 76 | .Nm 77 | as well; in particular, make sure to properly configure the clients' 78 | access rights, as described in 79 | .Xr s6-fdholderd 8 . 80 | .Pp 81 | .Nm 82 | is meant to be used in an s6 run script, as a supervised local 83 | service. 84 | It does not fork itself or write to syslog. 85 | However, it can be run under any infrastructure, including other 86 | supervision infrastructures, OpenRC, systemd, or SysV scripts. 87 | .Sh OPTIONS 88 | .Bl -tag -width x 89 | .It Fl 1 90 | Write a newline to stdout, before closing it, right after binding and 91 | listening to the Unix socket. 92 | If stdout is suitably redirected, this can be used by monitoring 93 | programs to check when the server is ready to accept connections. 94 | .It Fl v Ar verbosity 95 | Be quiet, normally verbose, or more verbose, depending on if verbosity 96 | is 0, 1, or more. 97 | The default is 1. 98 | .It Fl d 99 | Allow instant rebinding to the same path even if it has been used not 100 | long ago - this is the 101 | .Dv SO_REUSEADDR 102 | flag to 103 | .Xr setsockopt 2 104 | and is generally used with server programs. 105 | This is the default. 106 | Note that 107 | .Ar path 108 | will be deleted if it already exists at program start time. 109 | .It Fl D 110 | Disallow instant rebinding to the same path. 111 | .It Fl c Ar maxconn 112 | Accept at most 113 | .Ar maxconn 114 | concurrent client connections. 115 | Default is 16. 116 | It is impossible to set it higher than the value of the 117 | .Dv S6_FDHOLDER_MAX 118 | macro, which is 256. 119 | Client connections to this server are short-lived, so this number 120 | needs not be too high. 121 | Every client connection eats up one available file descriptor, so it 122 | is best for 123 | .Ar maxconn 124 | to be as small as possible. 125 | .It Fl n Ar maxfds 126 | Store at most 127 | .Ar maxfds 128 | file descriptors. 129 | Default is 1000. 130 | It is impossible to set it higher than the number of files that can be 131 | opened by the 132 | .Nm 133 | process minus a few descriptors needed for correct 134 | .Xr s6-fdholderd 8 135 | operation. 136 | Before running 137 | .Nm , 138 | make sure to properly adjust, via 139 | .Xr s6-softlimit 8 , 140 | the number of openable files[1] of the current process. 141 | .It Fl b Ar backlog 142 | Set a maximum of 143 | .Ar backlog 144 | backlog connections on the socket. 145 | Extra connection attempts will rejected by the kernel. 146 | .It Fl G Ar gidlist 147 | Change 148 | .Nm Ap 149 | s supplementary group list to 150 | .Ar gidlist 151 | after binding the socket. 152 | This is only valid when run as root. 153 | .Ar gidlist 154 | must be a comma-separated list of numerical group IDs. 155 | .It Fl g Ar gid 156 | Change 157 | .Nm Ap 158 | s groupid to 159 | .Ar gid 160 | after binding the socket. 161 | This is only valid when run as root. 162 | .It Fl u Ar uid 163 | Change 164 | .Nm Ap 165 | s userid to 166 | .Ar uid 167 | after binding the socket. 168 | This is only valid when run as root. 169 | .It Fl U 170 | Change 171 | .Nm Ap 172 | s user id, group id and supplementary group list according to the 173 | values of the 174 | .Ev UID , 175 | .Ev GID 176 | and 177 | .Ev GIDLIST 178 | environment variables after binding the socket. 179 | This is only valid when run as root. 180 | This can be used with the 181 | .Xr s6-envuidgid 8 182 | program to easily script a service that binds to a privileged socket 183 | then drops its privileges to those of a named non-root account. 184 | .It Fl t Ar clienttimeout 185 | Disconnect a client if it's in the middle of an operation and it has 186 | not written or read any data in 187 | .Ar clienttimeout 188 | milliseconds. 189 | By default, 190 | .Ar clienttimeout 191 | is 0, which means infinite. 192 | .It Fl T Ar lameducktimeout 193 | Give clients 194 | .Ar lameducktimeout 195 | milliseconds to finish their current operation before exiting after 196 | .Xr s6-fdholderd 8 197 | has received a SIGTERM. 198 | By default, 199 | .Ar lameducktimeout 200 | is 0, which means infinite. 201 | .It Fl x Ar rulesfile 202 | Read access rights configuration from CDB file 203 | .Ar rulesfile . 204 | .It Fl i Ar rulesdir 205 | Read access rights configuration from the filesystem in directory 206 | .Ar rulesdir . 207 | .El 208 | .Sh SEE ALSO 209 | .Xr s6-fdholder-delete 8 , 210 | .Xr s6-fdholder-getdump 8 , 211 | .Xr s6-fdholder-list 8 , 212 | .Xr s6-fdholder-retrieve 8 , 213 | .Xr s6-fdholder-setdump 8 , 214 | .Xr s6-fdholder-store 8 , 215 | .Xr s6-fdholder-transferdump 8 , 216 | .Xr s6-fdholderd 8 217 | .Pp 218 | [1] 219 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_resource.h.html 220 | .Pp 221 | This man page is ported from the authoritative documentation at: 222 | .Lk https://skarnet.org/software/s6/s6-fdholder-daemon.html 223 | .Sh AUTHORS 224 | .An Laurent Bercot 225 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 226 | -------------------------------------------------------------------------------- /man8/s6-fdholder-delete.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-DELETE 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-delete 6 | .Nd connect to an 7 | .Xr s6-fdholderd 8 8 | daemon listening on a Unix domain socket, and delete a file 9 | descriptor from the daemon storage 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl t Ar timeout 13 | .Ar path 14 | .Ar id 15 | .Sh DESCRIPTION 16 | .Nm 17 | connects to an 18 | .Xr s6-fdholderd 8 19 | server process listening on 20 | .Ar path . 21 | .Pp 22 | It tells the server to close the file descriptor that has been stored 23 | with identifier 24 | .Ar id . 25 | .Sh OPTIONS 26 | .Bl -tag -width x 27 | .It Fl t Ar timeout 28 | If the operation cannot be processed in 29 | .Ar timeout 30 | milliseconds, then fail with an error message. 31 | Communications with the server should be near-instant, so this option 32 | is only here to protect users against programming errors (connecting 33 | to the wrong socket, for instance). 34 | .El 35 | .Sh EXIT STATUS 36 | .Bl -tag -width x 37 | .It 0 38 | Success. 39 | .It 1 40 | The server denied the operation. 41 | The meanings of the error messages are explained in 42 | .Xr s6-fdholder-error-codes 7 . 43 | .It 100 44 | Wrong usage. 45 | .It 111 46 | System call failed - this includes attempting to connect to a 47 | nonexistent socket, or one where no 48 | .Xr s6-fdholderd 8 49 | daemon is listening. 50 | .El 51 | .Sh EXAMPLES 52 | .Dl s6-fdholder-delete /service/fdholderd/s MYSOCKET 53 | .Pp 54 | will tell an 55 | .Xr s6-fdholderd 8 56 | daemon listening on the 57 | .Pa /service/fdholderd/s 58 | socket to close the file descriptor identified as 59 | .Ql MYSOCKET . 60 | .Sh SEE ALSO 61 | .Xr s6-fdholder-daemon 8 , 62 | .Xr s6-fdholder-getdump 8 , 63 | .Xr s6-fdholder-list 8 , 64 | .Xr s6-fdholder-retrieve 8 , 65 | .Xr s6-fdholder-setdump 8 , 66 | .Xr s6-fdholder-store 8 , 67 | .Xr s6-fdholder-transferdump 8 , 68 | .Xr s6-fdholderd 8 69 | .Pp 70 | This man page is ported from the authoritative documentation at: 71 | .Lk https://skarnet.org/software/s6/s6-fdholder-delete.html 72 | .Sh AUTHORS 73 | .An Laurent Bercot 74 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 75 | -------------------------------------------------------------------------------- /man8/s6-fdholder-getdump.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-GETDUMP 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-getdump 6 | .Nd connect to an 7 | .Xr s6-fdholderd 8 8 | daemon listening on a Unix domain socket, and retrieves its entire 9 | state: file descriptors with their identifiers and expiration dates 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl t Ar timeout 13 | .Ar path 14 | .Ar prog... 15 | .Sh DESCRIPTION 16 | .Nm 17 | connects to an 18 | .Xr s6-fdholderd 8 19 | server process listening on 20 | .Ar path . 21 | .Pp 22 | It retrieves a copy of the whole set of file descriptors stored in 23 | this daemon, including their identifiers and expiration dates. 24 | .Pp 25 | It then executes into 26 | .Ar prog... 27 | with the additional open descriptors and the additional environment 28 | variables. 29 | .Pp 30 | Getting the whole state of an 31 | .Xr s6-fdholderd 8 32 | daemon requires specific privileges. 33 | Make sure you properly configure 34 | .Xr s6-fdholderd 8 35 | access rights so your client can perform that operation. 36 | .Sh OPTIONS 37 | .Bl -tag -width x 38 | .It Fl t Ar timeout 39 | If the operation cannot be processed in 40 | .Ar timeout 41 | milliseconds, then fail with an error message. 42 | Communications with the server should be near-instant, so this option 43 | is only here to protect users against programming errors (connecting 44 | to the wrong socket, for instance). 45 | .El 46 | .Sh ENVIRONMENT 47 | .Ar prog... 48 | is executed with the following environment variables set: 49 | .Bl -bullet -width x 50 | .It 51 | .Ev S6_FD# 52 | contains the number 53 | .Va n 54 | of file descriptors retrieved from the server. 55 | .It 56 | Then, for every 57 | .Va i 58 | between 0 and 59 | .Va n Ns -1 60 | inclusive: 61 | .Bl -tag -width x 62 | .It Ev S6_FD_ Ns Va i 63 | Contains the number of the 64 | .Va i Ns th 65 | open file descriptor. 66 | .It Ev S6_FDID_ Ns Va i 67 | Contains the identifier of the 68 | .Va i Ns th 69 | open file descriptor. 70 | .It Ev S6_FDLIMIT_ Ns Va i 71 | Contains the expiration date of the 72 | .Va i Ns th 73 | open file descriptor, if applicable. 74 | That date is stored in external TAI64N format[1]. 75 | If the file descriptor is not supposed to expire, this 76 | environment variable is not defined. 77 | .El 78 | .El 79 | .Sh EXIT STATUS 80 | On success, the program doesn't exit; instead, it execs into 81 | .Ar prog... . 82 | .Bl -tag -width x 83 | .It 1 84 | The server denied the operation. 85 | The meanings of the error messages are explained in 86 | .Xr s6-fdholder-error-codes 7 . 87 | .It 100 88 | Wrong usage. 89 | .It 111 90 | System call failed - this includes attempting to connect to a 91 | nonexistent socket, or one where no 92 | .Xr s6-fdholderd 8 93 | daemon is listening. 94 | .El 95 | .Sh EXAMPLES 96 | .Dl s6-fdholder-getdump /service/fdholderd/s s6-fdholder-setdump /service/fdholderd-2/s 97 | .Pp 98 | will get the state of the 99 | .Xr s6-fdholderd 8 100 | daemon listening on the 101 | .Pa /service/fdholderd/s 102 | socket, and transmit it to the other 103 | .Xr s6-fdholderd 8 104 | daemon listening on the 105 | .Pa /service/fdholderd-2/s 106 | socket. 107 | Note that in this precise case, the 108 | .Xr s6-fdholder-transferdump 8 109 | program does the same thing more efficiently. 110 | .Sh SEE ALSO 111 | .Xr s6-fdholder-daemon 8 , 112 | .Xr s6-fdholder-delete 8 , 113 | .Xr s6-fdholder-list 8 , 114 | .Xr s6-fdholder-retrieve 8 , 115 | .Xr s6-fdholder-setdump 8 , 116 | .Xr s6-fdholder-store 8 , 117 | .Xr s6-fdholder-transferdump 8 , 118 | .Xr s6-fdholderd 8 , 119 | .Pp 120 | [1] 121 | .Lk https://cr.yp.to/libtai/tai64.html#tai64n 122 | .Pp 123 | This man page is ported from the authoritative documentation at: 124 | .Lk https://skarnet.org/software/s6/s6-fdholder-getdump.html 125 | .Sh AUTHORS 126 | .An Laurent Bercot 127 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 128 | -------------------------------------------------------------------------------- /man8/s6-fdholder-list.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-LIST 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-list 6 | .Nd list the descriptors currently held by 7 | .Xr s6-fdholderd 8 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl t Ar timeout 11 | .Ar path 12 | .Sh DESCRIPTION 13 | .Nm 14 | connects to an 15 | .Xr s6-fdholderd 8 16 | server process listening on 17 | .Ar path . 18 | .Pp 19 | It gets the list of identifiers corresponding to the currently held 20 | file descriptors. 21 | It prints this list to stdout, one per line. 22 | .Sh OPTIONS 23 | .Bl -tag -width x 24 | .It Fl t Ar timeout 25 | If the operation cannot be processed in 26 | .Ar timeout 27 | milliseconds, then fail with an error message. 28 | Communications with the server should be near-instant, so this option 29 | is only here to protect users against programming errors (connecting 30 | to the wrong socket, for instance). 31 | .El 32 | .Sh EXIT STATUS 33 | .Bl -tag -width x 34 | .It 0 35 | Success. 36 | .It 1 37 | The server denied the operation. 38 | The meanings of the error messages are explained in 39 | .Xr s6-fdholder-error-codes 7 . 40 | .It 100 41 | Wrong usage. 42 | .It 111 43 | System call failed - this includes attempting to connect to a 44 | nonexistent socket, or one where no 45 | .Xr s6-fdholderd 8 46 | daemon is listening. 47 | .El 48 | .Sh SEE ALSO 49 | .Xr s6-fdholder-daemon 8 , 50 | .Xr s6-fdholder-delete 8 , 51 | .Xr s6-fdholder-getdump 8 , 52 | .Xr s6-fdholder-retrieve 8 , 53 | .Xr s6-fdholder-setdump 8 , 54 | .Xr s6-fdholder-store 8 , 55 | .Xr s6-fdholder-transferdump 8 , 56 | .Xr s6-fdholderd 8 57 | .Pp 58 | This man page is ported from the authoritative documentation at: 59 | .Lk https://skarnet.org/software/s6/s6-fdholder-list.html 60 | .Sh AUTHORS 61 | .An Laurent Bercot 62 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 63 | -------------------------------------------------------------------------------- /man8/s6-fdholder-retrieve.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-RETRIEVE 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-retrieve 6 | .Nd connect to an 7 | .Xr s6-fdholderd 8 8 | daemon listening on a Unix domain socket, retrieve a file descriptor 9 | from this daemon, then execute a program with this file descriptor as 10 | the program's standard input 11 | .Sh SYNOPSIS 12 | .Nm 13 | .Op Fl D 14 | .Op Fl t Ar timeout 15 | .Ar path 16 | .Ar id 17 | .Ar prog... 18 | .Sh DESCRIPTION 19 | .Nm 20 | connects to an 21 | .Xr s6-fdholderd 8 22 | server process listening on 23 | .Ar path . 24 | .Pp 25 | It attempts to retrieve a copy of the file descriptor that has been 26 | stored into that daemon under identifier 27 | .Ar id . 28 | .Pp 29 | It then executes into 30 | .Ar prog... , 31 | with the retrieved file descriptor as standard input. 32 | .Pp 33 | To execute 34 | .Ar prog 35 | with the newly retrieved file descriptor as number 36 | .Em n 37 | while preserving stdin, use the following construct: 38 | .Pp 39 | .Dl fdmove n 0 s6-fdholder-retrieve path id fdswap 0 n prog.... 40 | .Sh OPTIONS 41 | .Bl -tag -width x 42 | .It Fl D 43 | Delete the file descriptor from the server's storage after 44 | retrieval. 45 | This option requires writing rights over the given identifier as well 46 | as reading rights: check the server's configuration. 47 | Refer to 48 | .Xr s6-fdholder 7 49 | for details. 50 | .It Fl t Ar timeout 51 | If the operation cannot be processed in 52 | .Ar timeout 53 | milliseconds, then fail with an error message. 54 | Communications with the server should be near-instant, so this option 55 | is only here to protect users against programming errors (connecting 56 | to the wrong socket, for instance). 57 | .El 58 | .Sh EXIT STATUS 59 | On success, the program doesn't exit; instead, it execs into 60 | .Ar prog... . 61 | .Bl -tag -width x 62 | .It 1 63 | The server denied the operation. 64 | The meanings of the error messages are explained in 65 | .Xr s6-fdholder-error-codes 7 . 66 | .It 100 67 | Wrong usage. 68 | .It 111 69 | System call failed - this includes attempting to connect to a 70 | nonexistent socket, or one where no 71 | .Xr s6-fdholderd 8 72 | daemon is listening. 73 | .El 74 | .Sh EXAMPLES 75 | .Dl s6-fdholder-retrieve /service/fdholderd/s MYSOCKET s6-ipcserverd cat 76 | .Pp 77 | will retrieve a file descriptor stored under the 78 | .Ql MYSOCKET 79 | identifier in the 80 | .Xr s6-fdholderd 8 81 | daemon listening on the 82 | .Pa /service/fdholderd/s 83 | socket, and execute into 84 | .Ql s6-ipcserverd cat 85 | with this file descriptor as stdin. 86 | In this case, if 87 | .Ql MYSOCKET 88 | referred to a Unix domain socket, 89 | .Xr s6-ipcserverd 8 90 | will then accept client connections on it and spawn a 91 | .Ql cat 92 | program for every connection. 93 | .Sh SEE ALSO 94 | .Xr s6-fdholder-daemon 8 , 95 | .Xr s6-fdholder-delete 8 , 96 | .Xr s6-fdholder-getdump 8 , 97 | .Xr s6-fdholder-list 8 , 98 | .Xr s6-fdholder-setdump 8 , 99 | .Xr s6-fdholder-store 8 , 100 | .Xr s6-fdholder-transferdump 8 , 101 | .Xr s6-fdholderd 8 102 | .Pp 103 | This man page is ported from the authoritative documentation at: 104 | .Lk https://skarnet.org/software/s6/s6-fdholder-retrieve.html 105 | .Sh AUTHORS 106 | .An Laurent Bercot 107 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 108 | -------------------------------------------------------------------------------- /man8/s6-fdholder-setdump.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-SETDUMP 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-setdump 6 | .Nd connect to an 7 | .Xr s6-fdholderd 8 8 | daemon listening on a Unix domain socket, and dump a set of file 9 | descriptors into that daemon 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl t Ar timeout 13 | .Ar path 14 | .Sh DESCRIPTION 15 | .Nm 16 | connects to an 17 | .Xr s6-fdholderd 8 18 | server process listening on 19 | .Ar path . 20 | .Pp 21 | It attempts to pass a complete state - i.e. a set of file descriptors 22 | with identifiers and expiration dates - to the server. 23 | .Pp 24 | The file descriptors to transmit to the server should of course be 25 | already open in the 26 | .Nm 27 | program; also, 28 | .Nm 29 | should have certain environment variables that describe that set of 30 | file descriptors. 31 | The format of the environment is the same as the one set by 32 | .Xr s6-fdholder-getdump 8 . 33 | .Pp 34 | Setting the whole state of an 35 | .Xr s6-fdholderd 8 36 | daemon requires specific privileges. 37 | Make sure you properly configure 38 | .Xr s6-fdholderd 8 39 | access rights so your client can perform that operation. 40 | .Pp 41 | Previously held fds will still be kept by the server (so, 42 | .Dq setting 43 | the state is more like 44 | .Dq adding to 45 | the state), unless there is an identifier collision, in which case the 46 | fd in the transmitted set takes precedence and the previously held fd 47 | is overwritten. 48 | .Sh OPTIONS 49 | .Bl -tag -width x 50 | .It Fl t Ar timeout 51 | If the operation cannot be processed in 52 | .Ar timeout 53 | milliseconds, then fail with an error message. 54 | Communications with the server should be near-instant, so this option 55 | is only here to protect users against programming errors (connecting 56 | to the wrong socket, for instance). 57 | .El 58 | .Sh EXIT STATUS 59 | .Bl -tag -width x 60 | .It 0 61 | Success. 62 | .It 1 63 | The server denied the operation. 64 | The meanings of the error messages are explained in 65 | .Xr s6-fdholder-error-codes 7 . 66 | .It 100 67 | Wrong usage. 68 | .It 111 69 | System call failed - this includes attempting to connect to a 70 | nonexistent socket, or one where no 71 | .Xr s6-fdholderd 8 72 | daemon is listening. 73 | .El 74 | .Sh SEE ALSO 75 | .Xr s6-fdholder-daemon 8 , 76 | .Xr s6-fdholder-delete 8 , 77 | .Xr s6-fdholder-getdump 8 , 78 | .Xr s6-fdholder-list 8 , 79 | .Xr s6-fdholder-retrieve 8 , 80 | .Xr s6-fdholder-store 8 , 81 | .Xr s6-fdholder-transferdump 8 , 82 | .Xr s6-fdholderd 8 83 | .Pp 84 | This man page is ported from the authoritative documentation at: 85 | .Lk https://skarnet.org/software/s6/s6-fdholder-setdump.html 86 | .Sh AUTHORS 87 | .An Laurent Bercot 88 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 89 | -------------------------------------------------------------------------------- /man8/s6-fdholder-store.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-STORE 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-store 6 | .Nd connect to an 7 | .Xr s6-fdholderd 8 8 | daemon listening on a Unix domain socket, and give it a copy of one of 9 | its open file descriptors for the daemon to hold 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl d Ar fd 13 | .Op Fl T Ar fdtimeout 14 | .Op Fl t Ar timeout 15 | .Ar path 16 | .Ar id 17 | .Sh DESCRIPTION 18 | .Nm 19 | connects to an 20 | .Xr s6-fdholderd 8 21 | server process listening on 22 | .Ar path . 23 | .Pp 24 | It attempts to pass a copy of its standard input, or of its descriptor 25 | .Ar fd , 26 | to the server, with identifier 27 | .Ar id . 28 | .Sh OPTIONS 29 | .Bl -tag -width x 30 | .It Fl d Ar fd 31 | Store descriptor number 32 | .Ar fd . 33 | By default, 34 | .Ar fd 35 | is 0 (i.e. the program's stdin will be stored). 36 | .It Fl T Ar fdtimeout 37 | The descriptor is stored with an expiration time of 38 | .Ar fdtimeout 39 | milliseconds, which means the 40 | .Xr s6-fdholderd 8 41 | daemon will close and get rid of the descriptor after this time. 42 | By default, 43 | .Ar fdtimeout 44 | is 0, which means infinite - no expiration time. 45 | .It Fl t Ar timeout 46 | If the operation cannot be processed in 47 | .Ar timeout 48 | milliseconds, then fail with an error message. 49 | Communications with the server should be near-instant, so this option 50 | is only here to protect users against programming errors (connecting 51 | to the wrong socket, for instance). 52 | .El 53 | .Sh EXIT STATUS 54 | .Bl -tag -width x 55 | .It 0 56 | Success. 57 | .It 1 58 | The server denied the operation. 59 | The meanings of the error messages are explained in 60 | .Xr s6-fdholder-error-codes 7 . 61 | .It 100 62 | Wrong usage. 63 | .It 111 64 | System call failed - this includes attempting to connect to a 65 | nonexistent socket, or one where no 66 | .Xr s6-fdholderd 8 67 | daemon is listening. 68 | .El 69 | .Sh EXAMPLES 70 | .Dl s6-ipcserver-socketbinder /tmp/mysocket s6-fdholder-store /service/fdholderd/s MYSOCKET 71 | .Pp 72 | will open a Unix domain socket, bind it to 73 | .Pa /tmp/mysocket 74 | and listen to incoming connections, then give it to an 75 | .Xr s6-fdholderd 8 76 | instance listening on 77 | .Pa /service/fdholderd/s , 78 | with no expiration date, with the 79 | .Dq MYSOCKET 80 | identifier. 81 | Another program will be able to retrieve the socket later, using 82 | .Xr s6-fdholder-retrieve 8 . 83 | .Sh SEE ALSO 84 | .Xr s6-fdholder-daemon 8 , 85 | .Xr s6-fdholder-delete 8 , 86 | .Xr s6-fdholder-getdump 8 , 87 | .Xr s6-fdholder-list 8 , 88 | .Xr s6-fdholder-retrieve 8 , 89 | .Xr s6-fdholder-setdump 8 , 90 | .Xr s6-fdholder-transferdump 8 , 91 | .Xr s6-fdholderd 8 92 | .Pp 93 | This man page is ported from the authoritative documentation at: 94 | .Lk https://skarnet.org/software/s6/s6-fdholder-store.html 95 | .Sh AUTHORS 96 | .An Laurent Bercot 97 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 98 | -------------------------------------------------------------------------------- /man8/s6-fdholder-transferdump.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FDHOLDER-TRANSFERDUMP 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fdholder-transferdump 6 | .Nd connect to two separate 7 | .Xr s6-fdholderd 8 8 | daemons and transfer the content of the first one to the second one 9 | .Sh SYNOPSIS 10 | .Nm 11 | .\" '-T lint' reports "WARNING: skipping no-space macro", 12 | .\" but the rendered output is correct. 13 | .Op Fl t Ar timeoutfrom : Ns Ar timeoutto 14 | .Ar pathfrom 15 | .Ar pathto 16 | .Sh DESCRIPTION 17 | .Nm 18 | connects to an 19 | .Xr s6-fdholderd 8 20 | server process listening on 21 | .Ar pathfrom 22 | and gets the whole set of file descriptors from this server, with 23 | their identifiers and (when relevant) expiration dates. 24 | .Pp 25 | It then connects to a different instance of 26 | .Xr s6-fdholderd 8 , 27 | listening on 28 | .Ar pathto , 29 | and stores the set of file descriptors in it. 30 | The set is added to the second server, which keeps the descriptors it 31 | was already holding. 32 | .Pp 33 | Dumping the entire state of 34 | .Xr s6-fdholderd 8 35 | requires special authorizations. 36 | Make sure the 37 | .Xr s6-fdholderd 8 38 | instances are configured to accept dump-getting and dump-setting 39 | requests from your client. 40 | Refer to 41 | .Xr s6-fdholderd 8 42 | for details. 43 | .Pp 44 | A typical use case of 45 | .Nm 46 | is when the main fd-holding daemon needs to upgrade, or restart for 47 | some reason. 48 | Transferring the file descriptors into another, temporary, fd-holding 49 | daemon instance allows it to restart without losing the descriptors. 50 | .Sh OPTIONS 51 | .Bl -tag -width x 52 | .\" '-T lint' reports "WARNING: skipping no-space macro", 53 | .\" but the rendered output is correct. 54 | .It Fl t Ar timeoutfrom : Ns Ar timeoutto 55 | If the operations cannot be processed in 56 | .Ar timeoutfrom 57 | .Po 58 | for the connection to 59 | .Ar pathfrom 60 | .Pc 61 | or 62 | .Ar timeoutto 63 | .Po 64 | for the connection to 65 | .Ar pathto 66 | .Pc 67 | milliseconds, then fail with an error message. 68 | Communications with the servers should be near-instant, so this option 69 | is only here to protect users against programming errors (connecting 70 | to the wrong socket, for instance). 71 | .El 72 | .Sh EXIT STATUS 73 | .Bl -tag -width x 74 | .It 0 75 | Success. 76 | .It 1 77 | The source server denied the operation. 78 | The meanings of the error messages are explained in 79 | .Xr s6-fdholder-error-codes 7 . 80 | .It 2 81 | The destination server denied the operation. 82 | The meanings of the error messages are explained in 83 | .Xr s6-fdholder-error-codes 7 . 84 | .It 100 85 | Wrong usage. 86 | .It 111 87 | System call failed - this includes attempting to connect to a 88 | nonexistent socket, or one where no 89 | .Xr s6-fdholderd 8 90 | daemon is listening. 91 | .El 92 | .Sh SEE ALSO 93 | .Xr s6-fdholder-daemon 8 , 94 | .Xr s6-fdholder-delete 8 , 95 | .Xr s6-fdholder-getdump 8 , 96 | .Xr s6-fdholder-list 8 , 97 | .Xr s6-fdholder-retrieve 8 , 98 | .Xr s6-fdholder-setdump 8 , 99 | .Xr s6-fdholder-store 8 , 100 | .Xr s6-fdholderd 8 101 | .Pp 102 | This man page is ported from the authoritative documentation at: 103 | .Lk https://skarnet.org/software/s6/s6-fdholder-transferdump.html 104 | .Sh AUTHORS 105 | .An Laurent Bercot 106 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 107 | -------------------------------------------------------------------------------- /man8/s6-fghack.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FGHACK 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-fghack 6 | .Nd an anti-backgrounding tool 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar prog... 10 | .Sh DESCRIPTION 11 | .Nm 12 | opens a lot of file descriptors (all writing to a single pipe). 13 | .Pp 14 | Then it forks and executes 15 | .Ar prog... . 16 | .Pp 17 | If something gets written on one of those descriptors, it's a bug in 18 | .Ar prog . 19 | .Nm 20 | then complains and exits 102. 21 | .Pp 22 | Unless 23 | .Ar prog... 24 | goes out of its way to close descriptors it does not know about, 25 | .Nm 26 | is able to detect when 27 | .Ar prog... 28 | exits. 29 | It exits with the same exit code (or 111 if 30 | .Ar prog... 31 | has crashed). 32 | .Pp 33 | .Nm 34 | is what it says: a hack. 35 | Ideally, you should never have to use it. 36 | It is only useful when you want to supervise a daemon that does not 37 | provide a 38 | .Dq stay in the foreground 39 | option; and even then, the right thing is to report this as a bug to 40 | the daemon author and have it fixed. 41 | .Sh SEE ALSO 42 | .Xr s6-applyuidgid 8 , 43 | .Xr s6-envdir 8 , 44 | .Xr s6-envuidgid 8 , 45 | .Xr s6-setsid 8 , 46 | .Xr s6-setuidgid 8 , 47 | .Xr s6-softlimit 8 , 48 | .Xr s6-tai64n 8 , 49 | .Xr s6-tai64nlocal 8 50 | .Pp 51 | This man page is ported from the authoritative documentation at: 52 | .Lk https://skarnet.org/software/s6/s6-fghack.html 53 | .Sh AUTHORS 54 | .An Laurent Bercot 55 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 56 | -------------------------------------------------------------------------------- /man8/s6-ftrig-listen.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIG-LISTEN 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrig-listen 6 | .Nd subscribe to several 7 | .Xr s6-fifodir 7 Ns s , 8 | spawn a program, then wait for pattern of events to occur on the 9 | fifodirs 10 | .Sh SYNOPSIS 11 | In an 12 | .Xr execlineb 1 13 | script: 14 | .Pp 15 | .Nm 16 | .Op Fl a | o 17 | .Op Fl t Ar timeout 18 | .Bro 19 | .Ar fifodir-1 20 | .Ar regexp-1 21 | .Ar fifodir-2 22 | .Ar regexp-2 23 | .Brc 24 | .Ar prog... 25 | .Sh DESCRIPTION 26 | .Nm 27 | subscribes to 28 | .Ar fifodir1 29 | with the regexp 30 | .Ar regexp1 , 31 | to 32 | .Ar fifodir2 33 | with the regexp 34 | .Ar regexp2 , 35 | and so on. 36 | .Pp 37 | It then forks and execs 38 | .Ar prog... 39 | with all its arguments. 40 | .Pp 41 | It waits for the series of events received on 42 | .Ar fifodir Ns - Ns Em i 43 | to match 44 | .Ar regexp Ns - Ns Em i . 45 | .Ar regexp Ns - Ns Em i 46 | must be Extended Regular Expressions[1]. 47 | .Pp 48 | When the series of read events matches the regexps, 49 | .Nm 50 | exits 0. 51 | .Nm 52 | can be used outside of an execlineb script by using the internal argv 53 | syntax, but this syntax is an implementation detail and is not 54 | documented as stable. 55 | In a shell script, use 56 | .Ql execlineb -Pc 's6-ftrig-listen ...' 57 | to get the benefits of the execlineb brace syntax. 58 | .Sh OPTIONS 59 | .Bl -tag -width x 60 | .It Fl t Ar timeout 61 | If the events on the fifodirs have not matched the regexps after 62 | .Ar timeout 63 | milliseconds, print an error message on stderr and exit 1. 64 | By default, 65 | .Nm 66 | waits indefinitely for a matching series of events. 67 | .It Fl a 68 | And (conjunction). 69 | .Nm 70 | will only exit when all the 71 | .Ar fifodir Ns - Ns Em i 72 | have been notified with events matching the corresponding 73 | .Ar regexp Ns - Ns Em i . 74 | This is the default. 75 | .It Fl o 76 | Or (disjunction). 77 | .Nm 78 | will exit as soon as one of the 79 | .Ar fifodir Ns - Ns Em i 80 | has been notified with events matching its 81 | .Ar regexp Ns - Ns Em i . 82 | .El 83 | .Sh SEE ALSO 84 | .Xr execlineb 1 , 85 | .Xr s6-cleanfifodir 8 , 86 | .Xr s6-ftrig-listen1 8 , 87 | .Xr s6-ftrig-notify 8 , 88 | .Xr s6-ftrig-wait 8 , 89 | .Xr s6-ftrigrd 8 , 90 | .Xr s6-mkfifodir 8 91 | .Pp 92 | [1] 93 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04 94 | .Pp 95 | This man page is ported from the authoritative documentation at: 96 | .Lk https://skarnet.org/software/s6/s6-ftrig-listen.html 97 | .Sh AUTHORS 98 | .An Laurent Bercot 99 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 100 | -------------------------------------------------------------------------------- /man8/s6-ftrig-listen1.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIG-LISTEN1 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrig-listen1 6 | .Nd subscribe to an 7 | .Xr s6-fifodir 7 , 8 | then spawn a program, waiting for a pattern of events to occur on the 9 | fifodir 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl t Ar timeout 13 | .Ar fifodir 14 | .Ar regexp 15 | .Ar prog... 16 | .Sh DESCRIPTION 17 | .Nm 18 | acts just as 19 | .Xr s6-ftrig-wait 8 , 20 | except it can make sure that the process sending the notifications is 21 | actually started after there is a listener for those events. 22 | .Pp 23 | .Nm 24 | subscribes to 25 | .Ar fifodir . 26 | .Pp 27 | It then forks and execs 28 | .Ar prog... 29 | with all its arguments. 30 | .Pp 31 | It waits for the series of events received on 32 | .Ar fifodir 33 | to match 34 | .Ar regexp . 35 | .Ar regexp 36 | must be an Extended Regular Expression[1]. 37 | .Pp 38 | When the series of read events matches 39 | .Ar regexp , 40 | .Nm 41 | prints the last event it received to stdout (one byte followed by a newline), 42 | then exits 0. 43 | .Sh OPTIONS 44 | .Bl -tag -width x 45 | .It Fl t Ar timeout 46 | If the events on 47 | .Ar fifodir 48 | have not matched 49 | .Ar regexp 50 | after 51 | .Ar timeout 52 | milliseconds, print an error message on stderr and exit 1. 53 | By default, 54 | .Nm 55 | waits indefinitely for a matching series of events. 56 | .El 57 | .Sh EXAMPLES 58 | The following sequence of shell commands has a race condition. 59 | .Pp 60 | In terminal 1: 61 | .Bd -literal -offset indent 62 | s6-mkfifodir /tmp/toto 63 | s6-ftrig-wait /tmp/toto "message" 64 | .Ed 65 | .Pp 66 | Then in terminal 2: 67 | .Bd -literal -offset indent 68 | s6-ftrig-notify /tmp/toto message 69 | .Ed 70 | .Pp 71 | Depending on the operating system's scheduler, there is the 72 | possibility that the 73 | .Xr s6-ftrig-notify 8 74 | process starts sending 75 | .Dq message 76 | .Em before 77 | the 78 | .Xr s6-ftrig-wait 8 79 | process has actually subscribed to 80 | .Pa /tmp/toto , 81 | in which case the notification will be missed. 82 | The following sequence of shell commands accomplishes the same goal in 83 | a reliable way, without the race condition: 84 | .Bd -literal -offset indent 85 | s6-mkfifodir /tmp/toto 86 | s6-ftrig-listen1 /tmp/toto "message" s6-ftrig-notify /tmp/toto message 87 | .Ed 88 | .Sh SEE ALSO 89 | .Xr s6-cleanfifodir 8 , 90 | .Xr s6-ftrig-listen 8 , 91 | .Xr s6-ftrig-notify 8 , 92 | .Xr s6-ftrig-wait 8 , 93 | .Xr s6-ftrigrd 8 , 94 | .Xr s6-mkfifodir 8 95 | .Pp 96 | [1] 97 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04 98 | .Pp 99 | This man page is ported from the authoritative documentation at: 100 | .Lk https://skarnet.org/software/s6/s6-ftrig-listen1.html 101 | .Sh AUTHORS 102 | .An Laurent Bercot 103 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 104 | -------------------------------------------------------------------------------- /man8/s6-ftrig-notify.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIG-NOTIFY 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrig-notify 6 | .Nd send a series of events to an 7 | .Xr s6-fifodir 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Ar fifodir 11 | .Ar message 12 | .Sh DESCRIPTION 13 | .Nm 14 | notifies all the current listeners in 15 | .Ar fifodir 16 | with all the characters in 17 | .Ar message . 18 | .Pp 19 | .Nm 20 | cannot be used to send the null character (event 0x00). 21 | If you need to send the null character, use the C API: 22 | .Fn ftrigw_notify . Refer to 23 | .Xr s6-ftrigw 7 24 | for details. 25 | .Sh SEE ALSO 26 | .Xr s6-cleanfifodir 8 , 27 | .Xr s6-ftrig-listen 8 , 28 | .Xr s6-ftrig-listen1 8 , 29 | .Xr s6-ftrig-wait 8 , 30 | .Xr s6-ftrigrd 8 , 31 | .Xr s6-mkfifodir 8 32 | .Pp 33 | This man page is ported from the authoritative documentation at: 34 | .Lk https://skarnet.org/software/s6/s6-ftrig-notify.html 35 | .Sh AUTHORS 36 | .An Laurent Bercot 37 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 38 | -------------------------------------------------------------------------------- /man8/s6-ftrig-wait.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIG-WAIT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrig-wait 6 | .Nd subscribe to an 7 | .Xr s6-fifodir 7 8 | and wait for a pattern of events to occur on this fifodir 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl t Ar timeout 12 | .Ar fifodir 13 | .Ar regexp 14 | .Sh DESCRIPTION 15 | .Nm 16 | subscribes to 17 | .Ar fifodir . 18 | .Pp 19 | It waits for the series of events received on 20 | .Ar fifodir 21 | to match 22 | .Ar regexp . 23 | .Ar regexp 24 | must be an Extended Regular Expression[1]. 25 | .Pp 26 | When the series of read events matches 27 | .Ar regexp , 28 | .Nm 29 | prints the last event it received to stdout (one byte followed by a newline), 30 | then exits 0. 31 | .Sh OPTIONS 32 | .Bl -tag -width x 33 | .It Fl t Ar timeout 34 | If the events on 35 | .Ar fifodir 36 | have not matched 37 | .Ar regexp 38 | after 39 | .Ar timeout 40 | milliseconds, print an error message on stderr and exit 1. 41 | By default, 42 | .Nm 43 | waits indefinitely for a matching series of events. 44 | .El 45 | .Sh SEE ALSO 46 | .Xr s6-cleanfifodir 8 , 47 | .Xr s6-ftrig-listen 8 , 48 | .Xr s6-ftrig-listen1 8 , 49 | .Xr s6-ftrig-notify 8 , 50 | .Xr s6-ftrigrd 8 , 51 | .Xr s6-mkfifodir 8 52 | .Pp 53 | [1] 54 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04 55 | .Pp 56 | This man page is ported from the authoritative documentation at: 57 | .Lk https://skarnet.org/software/s6/s6-ftrig-wait.html 58 | .Sh AUTHORS 59 | .An Laurent Bercot 60 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 61 | -------------------------------------------------------------------------------- /man8/s6-ftrigrd.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-FTRIGRD 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ftrigrd 6 | .Nd helper program that manages a set of subscriptions to 7 | .Xr s6-fifodir 7 Ns s 8 | as well as regular expressions on events 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Sh DESCRIPTION 12 | .Nm 13 | takes orders from its client program that controls it via 14 | .Xr s6-ftrigr 7 , 15 | and notifies it when desired events happen. 16 | .Nm 17 | is not meant to be called directly. 18 | .Bl -bullet -width x 19 | .It 20 | If the client program uses 21 | .Fn ftrigr_startf , 22 | it spawns an instance of 23 | .Nm 24 | as a child. 25 | .Nm s6-ftrigrd Ap 26 | s stdin is a pipe reading from the client; its stdout is a pipe 27 | writing to the client; its stderr is the same as the client's; and 28 | there's an additional pipe from 29 | .Nm 30 | to the client, used for asynchronous notifications. 31 | .It 32 | If the client program uses 33 | .Fn ftrigr_start , 34 | then it tries to connect to a Unix domain socket. 35 | An 36 | .Nm 37 | local service should be listening to that socket, i.e. a Unix domain 38 | super-server such as 39 | .Xr s6-ipcserver 8 40 | spawning an 41 | .Nm 42 | program on every connection. 43 | Then an 44 | .Nm 45 | instance is created for the client. 46 | .It 47 | When the client uses 48 | .Fn ftrigr_end , or closes 49 | .Nm s6-ftrigrd Ap 50 | s stdin in any way, 51 | .Nm 52 | exits 0. 53 | .El 54 | .Pp 55 | .Nm 56 | handles the grunt work of creating fifos in a fifodir for a 57 | subscriber. 58 | It also wakes up on every event, and compares the chain of events it 59 | received on a given fifodir with the client-provided regexp. 60 | If the chain of events matches the regexp, it notifies the client. 61 | .Pp 62 | The connection management between the client and 63 | .Nm 64 | is entirely done by the textclient library from skalibs[1]. 65 | .Pp 66 | .Nm 67 | is entirely asynchronous. 68 | It stores unread notifications into heap memory; it can grow in size 69 | if there are a lot of events and the client fails to read them. 70 | To avoid uncontrolled growth, make sure your client calls 71 | .Fn ftrigr_update 72 | as soon as 73 | .Fn ftrigr_fd 74 | becomes readable. 75 | .Pp 76 | An 77 | .Nm 78 | instance can only handle up to 79 | .Dv FTRIGRD_MAX 80 | .Po 81 | defined in 82 | .Pa s6/ftrigr.h 83 | .Pc 84 | subscriptions at once. 85 | By default, this number is 1000, which is more than enough for any 86 | reasonable system. 87 | .Sh SEE ALSO 88 | .Xr s6-cleanfifodir 8 , 89 | .Xr s6-ftrig-listen 8 , 90 | .Xr s6-ftrig-listen1 8 , 91 | .Xr s6-ftrig-notify 8 , 92 | .Xr s6-ftrig-wait 8 , 93 | .Xr s6-mkfifodir 8 94 | .Pp 95 | [1] 96 | .Lk https://skarnet.org/software/skalibs/ 97 | .Pp 98 | This man page is ported from the authoritative documentation at: 99 | .Lk https://skarnet.org/software/s6/libs6/s6-ftrigrd.html 100 | .Sh AUTHORS 101 | .An Laurent Bercot 102 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 103 | -------------------------------------------------------------------------------- /man8/s6-instance-control.8: -------------------------------------------------------------------------------- 1 | .Dd January 11, 2023 2 | .Dt S6-INSTANCE-CONTROL 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instance-control 6 | .Nd send commands to a running instance of an 7 | .Xr s6-instanced-service 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl wu | Fl wU | Fl wd | Fl wD | Fl wr | Fl wR ] 11 | .Op Fl T Ar timeout 12 | .Op Fl abqhkti12pcyroduDUxO 13 | .Ar servicedir 14 | .Ar name 15 | 16 | .Sh DESCRIPTION 17 | .Nm 18 | expects a running, supervised 19 | .Xr s6-instanced-service 7 20 | in 21 | .Ar servicedir , 22 | as well as an existing instance of this service named 23 | .Ar name . 24 | .Pp 25 | It sends the given series of commands to the supervisor monitoring the 26 | .Ar name 27 | instance. 28 | .Pp 29 | It exits 0. 30 | .Sh OPTIONS 31 | The options, and the commands they represent, are exactly the same as 32 | the ones understood by 33 | .Xr s6-svc 8 . 34 | .Pp 35 | In fact, 36 | .Nm 37 | is nothing more than a call to 38 | .Xr s6-svc 8 39 | on the service directory representing the 40 | .Ar name 41 | instance. 42 | It is syntactic sugar so the user does not have to depend on the 43 | internal representation of instances and the location of instances' 44 | service directories. 45 | .Sh EXIT STATUS 46 | .Bl -tag -width x 47 | .It 0 48 | Success. 49 | .It 99 50 | With one of the 51 | .Fl w 52 | options, timed out while waiting for the command to complete. 53 | .It 100 54 | Wrong usage. 55 | .It 111 56 | System call failed. 57 | .El 58 | .Sh SEE ALSO 59 | .Xr s6-instanced-service 7 , 60 | .Xr s6-instance-create 8 , 61 | .Xr s6-instance-delete 8 , 62 | .Xr s6-instance-list 8 , 63 | .Xr s6-instance-maker 8 , 64 | .Xr s6-instance-status 8 65 | .Sh AUTHORS 66 | .An Laurent Bercot 67 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 68 | -------------------------------------------------------------------------------- /man8/s6-instance-create.8: -------------------------------------------------------------------------------- 1 | .Dd January 11, 2023 2 | .Dt S6-INSTANCE-CREATE 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instance-create 6 | .Nd create a new instance of a currently supervised 7 | .Xr s6-instanced-service 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl d | Fl D 11 | .Op Fl P 12 | .Op Fl f 13 | .Op Fl t Ar timeout 14 | .Ar servicedir 15 | .Ar name 16 | .Sh DESCRIPTION 17 | .Nm 18 | expects a running, supervised 19 | .Xr s6-instanced-service 7 20 | in 21 | .Ar servicedir . 22 | This service typically has been created by linking the result of an 23 | .Xr s6-instance-maker 8 24 | invocation into an existing 25 | .Xr s6-scan-directory 7 . 26 | .Pp 27 | .Nm 28 | creates a new instance of that service, named 29 | .Ar name . 30 | Depending on the given options, it may start it immediately, or keep 31 | it down until a later 32 | .Xr s6-instance-control 8 33 | invocation. 34 | .Pp 35 | It waits for the new instance to be ready to take commands from 36 | .Xr s6-instance-control 8 37 | .Pp 38 | It exits 0. 39 | .Pp 40 | .Nm 41 | is similar to 42 | .Xr s6-svlink 8 , 43 | because it uses the same underlying library functions. 44 | Under the hood, an instance is a regular service running on a 45 | supervision tree that is specific to the instanced service, and 46 | .Nm 47 | adds a service directory to that tree and ensures it gets 48 | supervised. 49 | .Pp 50 | If the template for the service is logged, then 51 | .Nm 52 | will wait until supervisors have been spawned for both the instance 53 | and its logger. 54 | .Pp 55 | .Nm 56 | and 57 | .Xr s6-instance-delete 8 58 | are relatively expensive operations, because they have to recursively 59 | copy or delete directories and use the 60 | .Xr s6-ftrigr 7 61 | synchronization mechanism with the instance supervisor, compared to 62 | .Xr s6-instance-control 8 63 | which only has to send commands to already existing supervisors. 64 | If you are going to turn instances on and off on a regular basis, it 65 | is more efficient to keep the instance existing and control it with 66 | .Xr s6-instance-control 8 67 | than it is to repeatedly create and delete it. 68 | .Sh OPTIONS 69 | .Bl -tag -width x 70 | .It Fl d 71 | Down. 72 | The instance supervisor will be started, but the instance 73 | itself will remain down. 74 | Any 75 | .Pa down 76 | file for the instance will be deleted. 77 | By default, if neither the 78 | .Fl d 79 | nor 80 | .Fl D 81 | options have been given, the supervisor auto-starts the instance as 82 | soon as it runs. 83 | .It Fl D 84 | Down, and stay down. 85 | The instance supervisor will be started, but the instance itself will 86 | remain down. 87 | A 88 | .Pa down 89 | file will be created for the instance. 90 | By default, if neither the 91 | .Fl d 92 | nor 93 | .Fl D 94 | options have been given, the supervisor auto-starts the instance as 95 | soon as it runs. 96 | .It Fl P 97 | Public. 98 | Everyone will be able to subscribe to the instance supervisor's 99 | notification. 100 | By default, only processes running with the same gid as the instanced 101 | service can subscribe to it. 102 | .It Fl f 103 | Force permissions. 104 | You should never need to use this option, it is only there for testing 105 | purposes. 106 | .It Fl t Ar timeout 107 | If the 108 | instance supervisor has not started after 109 | .Ar timeout 110 | milliseconds, 111 | .Nm 112 | will print a message to stderr and exit 99. 113 | By default, 114 | .Ar timeout 115 | is 0, which means no time limit. 116 | .El 117 | .Sh EXIT STATUS 118 | .Bl -tag -width -x 119 | .It 0 120 | Success. 121 | .It 99 122 | Timeout while waiting for the instance supervisor to start. 123 | .It 100 124 | Wrong usage. 125 | .It 111 126 | System call failed. 127 | .El 128 | .Sh SEE ALSO 129 | .Xr s6-instanced-service 7 , 130 | .Xr s6-instance-control 8 , 131 | .Xr s6-instance-delete 8 , 132 | .Xr s6-instance-list 8 , 133 | .Xr s6-instance-maker 8 , 134 | .Xr s6-instance-status 8 135 | .Sh AUTHORS 136 | .An Laurent Bercot 137 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 138 | -------------------------------------------------------------------------------- /man8/s6-instance-delete.8: -------------------------------------------------------------------------------- 1 | .Dd January 11, 2023 2 | .Dt S6-INSTANCE-DELETE 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instance-delete 6 | .Nd delete an existing instance of a currently supervised 7 | .Xr s6-instanced-service 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl X 11 | .Op Fl t Ar timeout 12 | .Ar servicedir 13 | .Ar name 14 | .Sh DESCRIPTION 15 | .Nm 16 | expects a running, supervised 17 | .Xr s6-instanced-service 7 18 | in 19 | .Ar servicedir , 20 | as well as an existing instance of this service named 21 | .Ar name 22 | (it doesn't matter if the instance is up or down). 23 | .Pp 24 | It deletes the 25 | .Ar name 26 | instance. 27 | .Pp 28 | It exits 0. 29 | .Pp 30 | .Nm 31 | is similar to 32 | .Xr s6-svunlink 8 , 33 | because it uses the same underlying library functions. 34 | Under the hood, an instance is a regular service running on a 35 | supervision tree that is specific to the instanced service, and 36 | .Nm 37 | removes a service directory from that tree. 38 | .Pp 39 | If the template for the service is logged, then 40 | .Nm 41 | will delete both the instance and its logger. 42 | .Pp 43 | .Nm 44 | and 45 | .Xr s6-instance-create 8 46 | are relatively expensive operations, because they have to recursively 47 | copy or delete directories and use the 48 | .Xr s6-ftrigr 7 49 | synchronization mechanism with the instance supervisor, compared to 50 | .Xr s6-instance-control 8 51 | which only has to send commands to already existing supervisors. 52 | If you are going to turn instances on and off on a regular basis, it 53 | is more efficient to keep the instance existing and control it with 54 | .Xr s6-instance-control 8 55 | than it is to repeatedly create and delete it. 56 | .Sh OPTIONS 57 | .Bl -tag -width x 58 | .It Fl X 59 | Don't wait. 60 | .Nm 61 | will exit right away, without waiting for the instance (and its 62 | supervisor) to properly disappear. 63 | .It Fl t Ar timeout 64 | If the instance supervisor has not exited after 65 | .Ar timeout 66 | milliseconds, 67 | .Nm 68 | will still exit. 69 | By default, 70 | .Ar timeout 71 | is 0, which means no time limit. 72 | .El 73 | .Sh EXIT STATUS 74 | .Bl -tag -width x 75 | .It 0 76 | Success. 77 | .It 100 78 | Wrong usage. 79 | .It 111 80 | System call failed. 81 | .El 82 | .Sh SEE ALSO 83 | .Xr s6-instanced-service 7 , 84 | .Xr s6-instance-control 8 , 85 | .Xr s6-instance-create 8 , 86 | .Xr s6-instance-list 8 , 87 | .Xr s6-instance-maker 8 , 88 | .Xr s6-instance-status 8 89 | .Sh AUTHORS 90 | .An Laurent Bercot 91 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 92 | -------------------------------------------------------------------------------- /man8/s6-instance-list.8: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt S6-INSTANCE-LIST 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instance-list 6 | .Nd give a list of all currently created instances of an 7 | .Xr s6-instanced-service 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Ar servicedir 11 | .Sh DESCRIPTION 12 | .Nm 13 | expects a running, supervised 14 | .Xr s6-instanced-service 7 15 | in 16 | .Ar servicedir , 17 | as well as an existing instance of this service named 18 | .Ar name . 19 | .Pp 20 | It prints to stdout, one per line, the names of all existing instances of 21 | .Ar servicedir , 22 | i.e. the ones that have been created and not deleted. 23 | It does not matter if the instances are up or down; if they've been 24 | created and not deleted, they're printed. 25 | .Pp 26 | It exits 0. 27 | .Pp 28 | The list is unsorted, the instance names are printed in an unspecified order. 29 | .Pp 30 | You can use 31 | .Nm 32 | to script commands that handle sets of instances. 33 | For example, to get the status of all the instances of a given 34 | service, you could write: 35 | .Ql for i in `s6-instance-list Ar service Ns ` ; do printf "%s: " $i ; s6-instance-status Ar service $i ; done 36 | .Sh EXIT STATUS 37 | .Bl -tag -width x 38 | .It 0 39 | Success. 40 | .It 100 41 | Wrong usage. 42 | .It 111 43 | System call failed. 44 | .El 45 | .Sh SEE ALSO 46 | .Xr s6-instanced-service 7 , 47 | .Xr s6-instance-control 8 , 48 | .Xr s6-instance-create 8 , 49 | .Xr s6-instance-delete 8 , 50 | .Xr s6-instance-maker 8 , 51 | .Xr s6-instance-status 8 52 | .Sh AUTHORS 53 | .An Laurent Bercot 54 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 55 | -------------------------------------------------------------------------------- /man8/s6-instance-status.8: -------------------------------------------------------------------------------- 1 | .Dd January 11, 2023 2 | .Dt S6-INSTANCE-STATUS 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-instance-status 6 | .Nd give the status of a running instance of an 7 | .Xr s6-instanced-service 7 , 8 | as a short human-readable summary or programmatically parsable output 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl uwNrpest | Fl o No up,wantedup,normallyup,ready,paused,pid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor 12 | .Op Fl n 13 | .Ar servicedir 14 | .Ar name 15 | .Sh DESCRIPTION 16 | .Nm 17 | expects a running, supervised 18 | .Xr s6-instanced-service 7 19 | in 20 | .Ar servicedir , 21 | as well as an existing instance of this service named 22 | .Ar name . 23 | .Pp 24 | It prints information to stdout about the monitored instance of 25 | .Ar servicedir 26 | named 27 | .Ar name . 28 | .Pp 29 | It exits 0. 30 | .Sh OPTIONS 31 | The options are exactly the same as the ones understood by 32 | .Xr s6-svstat 8 . 33 | .Pp 34 | In fact, s6-instance-status is nothing more than a call to 35 | .Xr s6-svstat 8 36 | on the service directory representing the 37 | .Ar name 38 | instance. 39 | It is syntactic sugar so the user does not have to depend on the 40 | internal representation of instances and the location of instances' 41 | service directories. 42 | .Sh EXIT STATUS 43 | .Bl -tag -width x 44 | .It 0 45 | Success. 46 | .It 100 47 | Wrong usage. 48 | .It 111 49 | System call failed. 50 | .El 51 | .Sh SEE ALSO 52 | .Xr s6-instanced-service 7 , 53 | .Xr s6-instance-control 8 , 54 | .Xr s6-instance-create 8 , 55 | .Xr s6-instance-delete 8 , 56 | .Xr s6-instance-list 8 , 57 | .Xr s6-instance-maker 8 58 | .Sh AUTHORS 59 | .An Laurent Bercot 60 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 61 | -------------------------------------------------------------------------------- /man8/s6-ioconnect.8: -------------------------------------------------------------------------------- 1 | .Dd February 19, 2023 2 | .Dt S6-IOCONNECT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ioconnect 6 | .Nd perform full-duplex data transmission between two sets of open file descriptors 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl t Ar millisecs 10 | .Op Fl r Ar fdr 11 | .Op Fl w Ar fdw 12 | .Sh DESCRIPTION 13 | .Nm 14 | reads data from its stdin and writes it as-is to file descriptor 7, 15 | which is assumed to be open. 16 | .Pp 17 | It also reads data from its file descriptor 6, which is assumed to be 18 | open, and writes it as-is to its stdout. 19 | .Pp 20 | When both sides have transmitted EOF and 21 | .Nm 22 | has flushed its buffers, it exits 0. 23 | .Pp 24 | The point of 25 | .Nm 26 | is to be used together with 27 | s6-tcpclient 28 | or 29 | .Xr s6-ipcclient 8 30 | to establish a full-duplex connection between the client and the 31 | server, for instance for testing purposes. 32 | .Nm 33 | is to 34 | s6-tcpclient 35 | as 36 | .Xr cat 1 37 | is to 38 | s6-tcpserver: 39 | a program that will just echo what it gets. 40 | .Pp 41 | The 42 | .Nm 43 | utility was once part of the s6-networking suite, which is why the 44 | examples here involve TCP. 45 | Nevertheless, it can be used with connections across Unix domain 46 | sockets as well, and has its place in the s6 package. 47 | .Pp 48 | If one of the endpoints is a socket, 49 | .Nm 50 | will call 51 | .Xr shutdown 2 52 | on it (for reading or writing, depending on the endpoint) when it 53 | needs to transmit EOF. 54 | This is a necessary workaround to a misdesign[1] of the socket API, 55 | but it could have unintended consequences when the socket is shared 56 | among several processes that expect a persistent connection. 57 | Most of the time, however, it is a mistake to share a data socket 58 | between processes, so 59 | .Nm Ap s 60 | behaviour is suited to an overwhelming majority of cases, and the 61 | exceptions are specialized enough that they won't need to use 62 | .Nm . 63 | .Sh OPTIONS 64 | .Bl -tag -width x 65 | .It Fl t Ar millisecs 66 | If no activity on either side happens for 67 | .Ar millisecs 68 | milliseconds, 69 | .Nm 70 | closes the connection on both ends and exits 1. 71 | By default, 72 | .Ar millisecs 73 | is 0, which means no such timeout. 74 | .It Fl r Ar fdr 75 | Use fd 76 | .Ar fdr 77 | for 78 | .Dq remote 79 | reading instead of fd 6. 80 | .It Fl w Ar fdw 81 | Use fd 82 | .Ar fdw 83 | for 84 | .Dq remote 85 | writing instead of fd 7. 86 | .El 87 | .Pp 88 | The 89 | .Fl 0 , 90 | .Fl 1 , 91 | .Fl 6 92 | and 93 | .Fl 7 94 | options are still recognized for compatibility, but do nothing; they 95 | are deprecated. 96 | They were previously used to tell 97 | .Nm 98 | that the local reading, local writing, remote reading and remote 99 | writing endpoints, respectively, were sockets \(em but this is now 100 | autodetected. 101 | .Sh SEE ALSO 102 | .Xr s6-accessrules-cdb-from-fs 8 , 103 | .Xr s6-accessrules-fs-from-cdb 8 , 104 | .Xr s6-connlimit 8 , 105 | .Xr s6-ipcclient 8 , 106 | .Xr s6-ipcserver 8 , 107 | .Xr s6-ipcserver-access 8 , 108 | .Xr s6-ipcserver-socketbinder 8 , 109 | .Xr s6-ipcserverd 8 110 | .Pp 111 | [1] 112 | .Lk https://cr.yp.to/tcpip/twofd.html 113 | .Pp 114 | This man page is ported from the authoritative documentation at: 115 | .Lk https://skarnet.org/software/s6/s6-ioconnect.html 116 | .Sh AUTHORS 117 | .An Laurent Bercot 118 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 119 | -------------------------------------------------------------------------------- /man8/s6-ipcclient.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-IPCCLIENT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ipcclient 6 | .Nd UCSPI client tool[1] for Unix domain sockets: connect to a socket, then execute into a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl q | Q | v 10 | .Op Fl p Ar localpath 11 | .Op Fl l Ar localname 12 | .Ar path 13 | .Ar prog... 14 | .Sh DESCRIPTION 15 | .Nm 16 | connects to a Unix domain socket on 17 | .Ar path . 18 | .Pp 19 | It executes into 20 | .Ar prog... 21 | with descriptor 6 reading from the socket and descriptor 7 writing to 22 | it. 23 | .Pp 24 | .Nm 25 | is mostly used to connect a client to an 26 | .Xr s6-local-service 7 27 | without having to implement networking in the client. 28 | For instance, the 29 | .Xr s6-sudo 8 30 | program does this. 31 | .Sh OPTIONS 32 | .Bl -tag -width x 33 | .It Fl q 34 | Be quiet. 35 | .It Fl Q 36 | Be normally verbose. 37 | This is the default. 38 | .It Fl v 39 | Be verbose. 40 | .It Fl p Ar localpath 41 | Bind the local socket to 42 | .Ar localpath 43 | before connecting to 44 | .Ar path . 45 | .It Fl l Ar localname 46 | Use 47 | .Ar localname 48 | as the value of the 49 | .Ev IPCLOCALPATH 50 | environment variable. 51 | .El 52 | .Sh ENVIRONMENT 53 | .Ar prog... 54 | is run with the following variables set: 55 | .Bl -tag -width x 56 | .It PROTO 57 | Always set to IPC. 58 | .It IPCLOCALPATH 59 | Set to the path associated with the local socket, if any. 60 | Be aware that it may contain arbitrary characters. 61 | .El 62 | .Sh SEE ALSO 63 | .Xr s6-accessrules-cdb-from-fs 8 , 64 | .Xr s6-accessrules-fs-from-cdb 8 , 65 | .Xr s6-connlimit 8 , 66 | .Xr s6-ioconnect 8 , 67 | .Xr s6-ipcserver 8 , 68 | .Xr s6-ipcserver-access 8 , 69 | .Xr s6-ipcserver-socketbinder 8 , 70 | .Xr s6-ipcserverd 8 71 | .Pp 72 | [1] 73 | .Lk https://cr.yp.to/proto/ucspi.txt 74 | .Pp 75 | This man page is ported from the authoritative documentation at: 76 | .Lk https://skarnet.org/software/s6/s6-ipcclient.html 77 | .Sh AUTHORS 78 | .An Laurent Bercot 79 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 80 | -------------------------------------------------------------------------------- /man8/s6-ipcserver-access.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-IPCSERVER-ACCESS 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ipcserver-access 6 | .Nd control tool for Unix domain sockets on systems where the 7 | .Fn getpeereid 8 | system call can be implemented 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl v Ar verbosity 12 | .Op Fl E | e 13 | .Op Fl l Ar localname 14 | .Op Fl i Ar rulesdir | Fl x Ar rulesfile 15 | .Ar prog... 16 | .Sh DESCRIPTION 17 | .Nm 18 | is meant to be run after 19 | .Xr s6-ipcserverd 8 20 | and before the application program on the 21 | .Xr s6-ipcserver 8 22 | command line. 23 | .Pp 24 | .Nm 25 | checks it is run under a UCSPI server tool such as 26 | .Xr s6-ipcserver 8 . 27 | .Pp 28 | It checks that the remote end of the connection fits the accepted 29 | criteria defined by the database contained in 30 | .Ar rulesdir 31 | or 32 | .Ar rulesfile . 33 | If the database tells it to reject the connection, the program exits 34 | 1. 35 | .Pp 36 | It sets up a few additional environment variables. 37 | .Pp 38 | It executes into 39 | .Ar prog... , 40 | unless the first matching rule in the rule database includes 41 | instructions to override 42 | .Ar prog... . 43 | .Ss Access rule checking 44 | .Nm 45 | checks its client connection against a ruleset. 46 | This ruleset can be implemented: 47 | .Bl -bullet -width x 48 | .It 49 | either in the filesystem as an arborescence of directories and files, 50 | if the 51 | .Fl i 52 | option has been given. 53 | This option is the most flexible one: the directory format is simple 54 | enough for scripts to understand and modify it, and the ruleset can be 55 | changed dynamically. 56 | This is practical, for instance, for roaming users. 57 | .It 58 | or in a CDB[1] file, if the 59 | .Fl x 60 | option has been given. 61 | This option is the most efficient one if the ruleset is static enough: 62 | a lot less system calls are needed to perform searches in a CDB than 63 | in the filesystem. 64 | .El 65 | .Pp 66 | The exact format of the ruleset is described in the 67 | .Xr s6-accessrules-cdb-from-fs 8 68 | page. 69 | .Pp 70 | .Nm 71 | first reads the client UID 72 | .Em uid 73 | and GID 74 | .Em gid 75 | from the 76 | .Ev ${PROTO}REMOTEEUID 77 | and 78 | .Ev ${PROTO}REMOTEEGID 79 | environment variables, and checks them with the 80 | .Fn s6_accessrules_keycheck_uidgid 81 | function - refer to 82 | .Xr s6-accessrules 7 . 83 | In other words, it tries to match: 84 | .Bl -bullet -width x 85 | .It 86 | (if the client's effective uid is the same as 87 | .Sm off 88 | .Nm Ap 89 | .Sm on 90 | effective uid) 91 | .Pa uid/self 92 | .It 93 | .Sm off 94 | .Pa uid/ 95 | .Em uid 96 | .Sm on 97 | .It 98 | (if the client's effective gid is the same as 99 | .Sm off 100 | .Nm Ap 101 | .Sm on 102 | effective gid) 103 | .Pa gid/self 104 | .It 105 | .Sm off 106 | .Pa gid/ 107 | .Em gid 108 | .Sm on 109 | .It 110 | .Pa uid/default 111 | .El 112 | .Pp 113 | in that order. 114 | If no 115 | .Dv S6_ACCESSRULES_ALLOW 116 | result can be obtained, the connection is denied. 117 | .Ss Environment and executable modifications 118 | .Nm 119 | interprets non-empty 120 | .Pa env 121 | subdirectories and 122 | .Pa exec 123 | files it finds in the first matching rule of the ruleset, as explained 124 | in the 125 | .Xr s6-accessrules-cdb-from-fs 8 126 | page. 127 | .Bl -bullet -width x 128 | .It 129 | An 130 | .Pa env 131 | subdirectory is interpreted as if the 132 | .Xr s6-envdir 8 133 | command had been called before executing 134 | .Ar prog : 135 | the environment is modified according to the contents of 136 | .Pa env . 137 | .It 138 | An 139 | .Pa exec 140 | file containing 141 | .Em newprog 142 | completely bypasses the rest of 143 | .Sm off 144 | .Nm Ap 145 | .Sm on 146 | command line. 147 | After environment modifications, if any, 148 | .Nm 149 | execs into 150 | .Ql execlineb -c newprog . 151 | Please be aware that the 152 | .Pa exec 153 | file functionality is only supported when s6 has been built with 154 | execline support. 155 | Otherwise, a warning message is printed and executable diversion is 156 | not performed. 157 | .El 158 | .Sh OPTIONS 159 | .Bl -tag -width x 160 | .It Fl v Ar verbosity 161 | Be more or less verbose, i.e. print more or less information to stderr: 162 | .Bl -tag -width x 163 | .It 0 164 | Only log error messages. 165 | .It 1 166 | Only log error and warning messages, and accepted connections. 167 | This is the default. 168 | .It 2 169 | Also log rejected connections and more warning messages. 170 | .El 171 | .It Fl E 172 | No environment. 173 | All environment variables potentially set by 174 | .Nm , 175 | as well as those set by 176 | .Xr s6-ipcserver 8 , 177 | will be unset instead. 178 | .It Fl e 179 | Set up environment variables normally. 180 | This is the default. 181 | .It Fl l Ar localname 182 | Use 183 | .Ar localname 184 | as the value for the 185 | .Ev ${PROTO}LOCALPATH 186 | environment variable, instead of looking it up via 187 | .Xr getsockname 2 . 188 | .It Fl i Ar rulesdir 189 | Check client credentials against a filesystem-based database in the 190 | .Ar rulesdir 191 | directory. 192 | .It Fl x Ar rulesfile 193 | Check client credentials against a CDB[1] database in the 194 | .Ar rulesfile 195 | file. 196 | .Fl i 197 | and 198 | .Fl x 199 | are mutually exclusive. 200 | If none of those options is given, no credential checking will be 201 | performed, and a warning will be emitted on every connection if 202 | .Ar verbosity 203 | is 2 or more. 204 | .El 205 | .Sh ENVIRONMENT 206 | .Nm 207 | expects to inherit some environment variables from its parent: 208 | .Bl -tag -width x 209 | .It PROTO 210 | Normally IPC, but could be anything else, like UNIX. 211 | .It ${PROTO}REMOTEEUID 212 | The effective UID of the client program connecting to the socket. 213 | .It ${PROTO}REMOTEEGID 214 | The effective GID of the client program connecting to the socket. 215 | .El 216 | .Pp 217 | Additionally, it exports the following variable before executing into 218 | .Ar prog... : 219 | .Bl -tag -width x 220 | .It ${PROTO}LOCALPATH 221 | Set to the local 222 | .Dq address 223 | of the socket, as reported by the 224 | .Xr getsockname 2 225 | system call, truncated to 99 characters max. 226 | .El 227 | .Pp 228 | Also, the access rules database can instruct 229 | .Nm 230 | to set up, or unset, more environment variables, depending on the 231 | client address. 232 | .Sh SEE ALSO 233 | .Xr s6-accessrules-cdb-from-fs 8 , 234 | .Xr s6-accessrules-fs-from-cdb 8 , 235 | .Xr s6-connlimit 8 , 236 | .Xr s6-ioconnect 8 , 237 | .Xr s6-ipcclient 8 , 238 | .Xr s6-ipcserver 8 , 239 | .Xr s6-ipcserver-socketbinder 8 , 240 | .Xr s6-ipcserverd 8 241 | .Pp 242 | [1] 243 | .Lk https://en.wikipedia.org/wiki/Cdb_(software) 244 | .Pp 245 | This man page is ported from the authoritative documentation at: 246 | .Lk https://skarnet.org/software/s6/s6-ipcserver-access.html 247 | .Sh AUTHORS 248 | .An Laurent Bercot 249 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 250 | -------------------------------------------------------------------------------- /man8/s6-ipcserver-socketbinder.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-IPCSERVER-SOCKETBINDER 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ipcserver-socketbinder 6 | .Nd bind a Unix domain socket, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl d | D 10 | .Op Fl b Ar backlog 11 | .Op Fl M | m 12 | .Op Fl a Ar perms 13 | .Op Fl B 14 | .Ar path 15 | .Ar prog... 16 | .Sh DESCRIPTION 17 | .Nm 18 | creates a Unix domain socket and binds it to 19 | .Ar path . 20 | It prepares the socket to accept connections by calling 21 | .Xr listen 2 . 22 | .Pp 23 | It then execs into 24 | .Ar prog... 25 | with the open socket as its standard input. 26 | .Pp 27 | The socket is provided 28 | .Sy non-blocking by default . 29 | .Pp 30 | .Nm 31 | is part of a set of basic blocks used to build a flexible Unix 32 | super-server. 33 | It normally should be given a command line crafted to make it execute 34 | into 35 | .Xr s6-ipcserverd 8 36 | to accept connections from clients, or into a program such as 37 | .Xr s6-applyuidgid 8 38 | to drop privileges before doing so. 39 | .Pp 40 | The 41 | .Xr s6-ipcserver 8 42 | program does exactly this. 43 | It implements a full Unix super-server by building a command line 44 | starting with 45 | .Nm 46 | and ending with 47 | .Xr s6-ipcserverd 8 48 | followed by the application program, and executing into it. 49 | .Sh OPTIONS 50 | .Bl -tag -width x 51 | .It Fl d 52 | Allow instant rebinding to the same path even if it has been used not 53 | long ago - this is the 54 | .Dv SO_REUSEADDR 55 | flag to 56 | .Xr setsockopt 2 57 | and is generally used with server programs. 58 | This is the default. 59 | Note that 60 | .Ar path 61 | will be deleted if it already exists at program start time. 62 | .It Fl D 63 | Disallow instant rebinding to the same path. 64 | .It Fl b Ar backlog 65 | Set a maximum of 66 | .Ar backlog 67 | backlog connections on the socket - extra connection attempts will 68 | rejected by the kernel. 69 | The default is 70 | .Dv SOMAXCONN , 71 | i.e. the maximum number allowed by the system. 72 | If backlog is 0, then the socket will be created, but it 73 | .Sy will not be listening . 74 | .It Fl M 75 | The type of the socket will be 76 | .Dv SOCK_STREAM . 77 | This is the default. 78 | .It Fl m 79 | The type of the socket will be 80 | .Dv SOCK_DGRAM . 81 | Note that by default 82 | .Dv SOCK_DGRAM 83 | sockets are not connection-mode, and 84 | .Xr listen 2 85 | will fail - so you should always give the 86 | .Fl b0 87 | option to 88 | .Nm 89 | along with 90 | .Fl m . 91 | .It Fl a Ar perms 92 | Create the socket with permissions 93 | .Ar perms , 94 | which is an octal number from 0000 to 0777. 95 | Default is 0777, meaning everyone can connect to it. 96 | 0700 means only processes having the same uid as the 97 | .Nm 98 | process can connect to it. 99 | .It Fl B 100 | The socket will be blocking. 101 | The default is nonblocking. 102 | .El 103 | .Sh SEE ALSO 104 | .Xr s6-accessrules-cdb-from-fs 8 , 105 | .Xr s6-accessrules-fs-from-cdb 8 , 106 | .Xr s6-connlimit 8 , 107 | .Xr s6-ioconnect 8 , 108 | .Xr s6-ipcclient 8 , 109 | .Xr s6-ipcserver 8 , 110 | .Xr s6-ipcserver-access 8 , 111 | .Xr s6-ipcserverd 8 112 | .Pp 113 | This man page is ported from the authoritative documentation at: 114 | .Lk https://skarnet.org/software/s6/s6-ipcserver-socketbinder.html 115 | .Sh AUTHORS 116 | .An Laurent Bercot 117 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 118 | -------------------------------------------------------------------------------- /man8/s6-ipcserver.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-IPCSERVER 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ipcserver 6 | .Nd UCSPI server tool[1] for Unix domain sockets, i.e. a super-server: accept connections from clients, and fork a program to handle each connection 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl 1 10 | .Op Fl q | Q | v 11 | .Op Fl d | D 12 | .Op Fl P | p 13 | .Op Fl a Ar perms 14 | .Op Fl c Ar maxconn 15 | .Op Fl C Ar localmaxconn 16 | .Op Fl b Ar backlog 17 | .Op Fl G Ar gidlist 18 | .Op Fl g Ar gid 19 | .Op Fl u Ar uid 20 | .Op Fl U 21 | .Ar path 22 | .Ar prog... 23 | .Sh DESCRIPTION 24 | .Nm 25 | binds a Unix domain socket to 26 | .Ar path . 27 | .Pp 28 | It can drop its root privileges. 29 | .Pp 30 | It closes its stdin and stdout. 31 | .Pp 32 | For every client connection to this socket, it forks. 33 | The child sets some environment variables, then executes 34 | .Ar prog... 35 | with stdin reading from the socket and stdout writing to it. 36 | .Pp 37 | Depending on the verbosity level, it logs what it does to stderr. 38 | .Pp 39 | It runs until killed by a signal. 40 | Depending on the received signal, it may kill its children before 41 | exiting. 42 | .Pp 43 | .Nm 44 | actually doesn't do any of this itself. 45 | It is a wrapper, rewriting the command line and executing into a chain 46 | of programs that perform those duties. 47 | .Pp 48 | Previous versions of 49 | .Nm 50 | were monolithic: it did the work of 51 | .Xr s6-ipcserver-socketbinder 8 , 52 | .Xr s6-applyuidgid 8 53 | and 54 | .Xr s6-ipcserverd 8 55 | itself. 56 | The functionality has now been split into several different programs 57 | because some service startup schemes require the daemon to get its 58 | socket from an external program instead of creating and binding it 59 | itself. 60 | The most obvious application of this is upgrading a long-lived 61 | process without losing existing connections. 62 | .Sh OPTIONS 63 | .Bl -tag -width x 64 | .It Fl 1 65 | Write a newline to stdout, before closing it, right after binding and 66 | listening to the Unix socket. 67 | If stdout is suitably redirected, this can be used by monitoring 68 | programs to check when the server is ready to accept connections. 69 | .It Fl q 70 | Be quiet. 71 | .It Fl Q 72 | Be normally verbose. 73 | This is the default. 74 | .It Fl v 75 | Be verbose. 76 | .It Fl d 77 | Allow instant rebinding to the same path even if it has been used not 78 | long ago - this is the 79 | .Dv SO_REUSEADDR 80 | flag to 81 | .Xr setsockopt 2 82 | and is generally used with server programs. 83 | This is the default. 84 | Note that 85 | .Ar path 86 | will be deleted if it already exists at program start time. 87 | .It Fl D 88 | Disallow instant rebinding to the same path. 89 | .It Fl P 90 | Disable client credentials lookups. 91 | The 92 | .Ev IPCREMOTEEUID 93 | and 94 | .Ev IPCREMOTEEGID 95 | environment variables will be unset in every instance of 96 | .Ar prog... . 97 | This is the portable option, because not every system supports 98 | credential lookup across Unix domain sockets; but it is not as secure. 99 | .It Fl p 100 | Enable client credentials lookups. 101 | This is the default; it works at least on Linux, Solaris, and *BSD 102 | systems. 103 | On systems that do not support it, every connection attempt will fail 104 | with a warning message. 105 | .It Fl c Ar maxconn 106 | Accept at most 107 | .Ar maxconn 108 | concurrent connections. 109 | Default is 40. 110 | It is impossible to set it higher than 1000. 111 | .It Fl C Ar localmaxconn 112 | Accept at most 113 | .Ar localmaxconn 114 | connections from the same user ID. 115 | Default is 40. 116 | It is impossible to set it higher than 117 | .Ar maxconn . 118 | .It Fl b Ar backlog 119 | Set a maximum of 120 | .Ar backlog 121 | backlog connections on the socket. 122 | Extra connection attempts will rejected by the kernel. 123 | .It Fl a Ar perms 124 | Create the socket with permissions 125 | .Ar perms , 126 | which is an octal number from 0000 to 0777. 127 | Default is 0777, meaning everyone can connect to it. 128 | 0700 means only processes having the same uid as the 129 | .Nm 130 | process can connect to it. 131 | .It Fl G Ar gidlist 132 | Change 133 | .Nm Ap 134 | s supplementary group list to 135 | .Ar gidlist 136 | after binding the socket. 137 | This is only valid when run as root. 138 | .Ar gidlist 139 | must be a comma-separated list of numerical group IDs. 140 | .It Fl g Ar gid 141 | Change 142 | .Nm Ap 143 | s groupid to 144 | .Ar gid 145 | after binding the socket. 146 | This is only valid when run as root. 147 | .It Fl u Ar uid 148 | Change 149 | .Nm Ap 150 | s userid to 151 | .Ar uid 152 | after binding the socket. 153 | This is only valid when run as root. 154 | .It Fl U 155 | Change 156 | .Nm Ap 157 | s user id, group id and supplementary group list according to the 158 | values of the 159 | .Ev UID , 160 | .Ev GID 161 | and 162 | .Ev GIDLIST 163 | environment variables after binding the socket. 164 | This is only valid when run as root. 165 | This can be used with the 166 | .Xr s6-envuidgid 8 167 | program to easily script a service that binds to a privileged socket 168 | then drops its privileges to those of a named non-root account. 169 | .El 170 | .Sh IMPLEMENTATION NOTES 171 | .Nm 172 | parses the options and arguments it is given, and builds a new command 173 | line with them. 174 | It then executes into that new command line. 175 | .Pp 176 | The first program 177 | .Nm s6-ipcserver 178 | executes into is 179 | .Xr s6-ipcserver-socketbinder 8 . 180 | It will create and bind a Unix domain socket to 181 | .Ar path , 182 | then execute into the rest of the command line. 183 | .Pp 184 | If a privilege-dropping operation has been requested, the program that 185 | .Xr s6-ipcserver-socketbinder 8 186 | executes into is 187 | .Xr s6-applyuidgid 8 . 188 | It will drop the root privileges, then execute into the rest of the 189 | command line. 190 | .Pp 191 | The next program in the chain is 192 | .Xr s6-ipcserverd 8 . 193 | It is executed into by 194 | .Xr s6-applyuidgid 8 , 195 | or directly by 196 | .Xr s6-ipcserver-socketbinder 8 197 | if no privilege-dropping operation has been requested. 198 | .Xr s6-ipcserverd 8 199 | is the long-lived process, the 200 | .Dq daemon 201 | itself, accepting connections from clients. 202 | .Pp 203 | For every client, 204 | .Xr s6-ipcserverd 8 205 | will spawn an instance of 206 | .Ar prog... , 207 | the remainder of the command line. 208 | .Sh SEE ALSO 209 | .Xr s6-accessrules-cdb-from-fs 8 , 210 | .Xr s6-accessrules-fs-from-cdb 8 , 211 | .Xr s6-connlimit 8 , 212 | .Xr s6-ioconnect 8 , 213 | .Xr s6-ipcclient 8 , 214 | .Xr s6-ipcserver-access 8 , 215 | .Xr s6-ipcserver-socketbinder 8 , 216 | .Xr s6-ipcserverd 8 217 | .Pp 218 | [1] 219 | .Lk https://cr.yp.to/proto/ucspi.txt 220 | .Pp 221 | This man page is ported from the authoritative documentation at: 222 | .Lk https://skarnet.org/software/s6/s6-ipcserver.html 223 | .Sh AUTHORS 224 | .An Laurent Bercot 225 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 226 | -------------------------------------------------------------------------------- /man8/s6-ipcserverd.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-IPCSERVERD 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-ipcserverd 6 | .Nd serving part of the 7 | .Xr s6-ipcserver 8 8 | super-server 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl 1 12 | .Op Fl v Ar verbosity 13 | .Op Fl P | p 14 | .Op Fl c Ar maxconn 15 | .Op Fl C Ar localmaxconn 16 | .Ar prog... 17 | .Sh DESCRIPTION 18 | .Nm 19 | assumes that its stdin is a bound and listening Unix domain socket, 20 | and it accepts connections from clients connecting to it, forking a 21 | program to handle each connection. 22 | .Pp 23 | .Nm 24 | accepts connections from clients to an already bound and listening 25 | .Dv SOCK_STREAM 26 | Unix domain socket which is its standard input. 27 | .Pp 28 | For every client connection to this socket, it forks. 29 | The child sets some environment variables, then executes 30 | .Ar prog... 31 | with stdin reading from the socket and stdout writing to it. 32 | .Pp 33 | Depending on the verbosity level, it logs what it does to stderr. 34 | .Pp 35 | It runs until killed by a signal. 36 | Depending on the received signal, it may kill its children before 37 | exiting. 38 | .Pp 39 | Unlike his close cousin ipcserver, 40 | .Nm 41 | does not perform operations such as access control. 42 | Those are delegated to the 43 | .Xr s6-ipcserver-access 8 44 | program. 45 | .Pp 46 | .Nm 47 | can be used to set up 48 | .Xr s6-local-service 7 Ns s . 49 | .Pp 50 | .Nm 51 | is meant to be execve'd into by a program that gets the listening 52 | socket. 53 | That program is normally 54 | .Xr s6-ipcserver-socketbinder 8 , 55 | which creates the socket itself; but it can be a different one if the 56 | socket is to be retrieved by another means, for instance by fd-passing 57 | from an fd-holding daemon 58 | .Po 59 | some people call this 60 | .Dq socket activation 61 | .Pc . 62 | .Ss Signals 63 | .Bl -tag -width x 64 | .It SIGTERM 65 | Exit. 66 | .It SIGHUP 67 | Send a SIGTERM and a SIGCONT to all children. 68 | .It SIGQUIT 69 | Send a SIGTERM and a SIGCONT to all children, then exit. 70 | .It SIGABRT 71 | Send a SIGKILL to all children, then exit. 72 | .El 73 | .Sh OPTIONS 74 | .Bl -tag -width x 75 | .It Fl 1 76 | Write a newline to stdout, and close stdout, right before entering the 77 | client-accepting loop. 78 | If stdout is suitably redirected, this can be used by monitoring 79 | programs to check when the server is accepting connections. 80 | See 81 | .Xr s6-notifywhenup 7 82 | for more information on readiness notification. 83 | .It Fl v Ar verbosity 84 | Be more or less verbose. 85 | .Ar verbosity 86 | can be 0 (quiet), 1 (normal), or 2 (verbose). 87 | .It Fl P 88 | Disable client credentials lookups. 89 | The 90 | .Ev IPCREMOTEEUID 91 | and 92 | .Ev IPCREMOTEEGID 93 | environment variables will be unset in every instance of 94 | .Ar prog... . 95 | This is the portable option, because not every system supports 96 | credential lookup across Unix domain sockets; but it is not as secure. 97 | .It Fl p 98 | Enable client credentials lookups. 99 | This is the default; it works at least on Linux, Solaris, and *BSD 100 | systems. 101 | On systems that do not support it, every connection attempt will fail 102 | with a warning message. 103 | .It Fl c Ar maxconn 104 | Accept at most 105 | .Ar maxconn 106 | concurrent connections. 107 | Default is 40. 108 | It is impossible to set it higher than 1000. 109 | .It Fl C Ar localmaxconn 110 | Accept at most 111 | .Ar localmaxconn 112 | connections from the same user ID. 113 | Default is 40. 114 | It is impossible to set it higher than 115 | .Ar maxconn . 116 | .El 117 | .Sh ENVIRONMENT 118 | For each connection, an instance of 119 | .Ar prog... 120 | is spawned with the following variables set: 121 | .Bl -tag -width x 122 | .It PROTO 123 | Always set to IPC. 124 | .It IPCREMOTEEUID 125 | Set to the effective UID of the client, unless credentials lookups 126 | have been disabled. 127 | .It IPCREMOTEEGID 128 | Set to the effective GID of the client, unless credentials lookups 129 | have been disabled. 130 | .It IPCREMOTEPATH 131 | Set to the path associated with the remote socket, if any. 132 | Be aware that it may contain arbitrary characters. 133 | .It IPCCONNNUM 134 | Set to the number of connections originating from the same user 135 | (i.e. same uid). 136 | .El 137 | .Pp 138 | If client credentials lookup has been disabled, 139 | .Ev IPCREMOTEEUID 140 | and 141 | .Ev IPCREMOTEEGID 142 | will be set, but empty. 143 | .Sh SEE ALSO 144 | .Xr s6-accessrules-cdb-from-fs 8 , 145 | .Xr s6-accessrules-fs-from-cdb 8 , 146 | .Xr s6-connlimit 8 , 147 | .Xr s6-ioconnect 8 , 148 | .Xr s6-ipcclient 8 , 149 | .Xr s6-ipcserver 8 , 150 | .Xr s6-ipcserver-access 8 , 151 | .Xr s6-ipcserver-socketbinder 8 152 | .Pp 153 | This man page is ported from the authoritative documentation at: 154 | .Lk https://skarnet.org/software/s6/s6-ipcserverd.html 155 | .Sh AUTHORS 156 | .An Laurent Bercot 157 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 158 | -------------------------------------------------------------------------------- /man8/s6-mkfifodir.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-MKFIFODIR 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-mkfifodir 6 | .Nd create an 7 | .Xr s6-fifodir 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl f 11 | .Op Fl g Ar gid 12 | .Ar fifodir 13 | .Sh DESCRIPTION 14 | .Nm 15 | creates 16 | .Ar fifodir , 17 | belonging to the current user. 18 | .Sh OPTIONS 19 | .Bl -tag -width x 20 | .It Fl f 21 | Force permissions. 22 | If 23 | .Ar fifodir 24 | already exists, change its permissions according to the 25 | .Fl g 26 | options. 27 | By default, if 28 | .Ar fifodir 29 | exists, 30 | .Nm 31 | does nothing. 32 | .It Fl g Ar gid 33 | Make 34 | .Ar fifodir 35 | only listenable by members of group 36 | .Ar gid . 37 | If this option is not given, the 38 | .Ar fifodir 39 | is made publically listenable. 40 | .El 41 | .Sh SEE ALSO 42 | .Xr s6-cleanfifodir 8 , 43 | .Xr s6-ftrig-listen 8 , 44 | .Xr s6-ftrig-listen1 8 , 45 | .Xr s6-ftrig-notify 8 , 46 | .Xr s6-ftrig-wait 8 , 47 | .Xr s6-ftrigrd 8 48 | .Pp 49 | This man page is ported from the authoritative documentation at: 50 | .Lk https://skarnet.org/software/s6/s6-mkfifodir.html 51 | .Sh AUTHORS 52 | .An Laurent Bercot 53 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 54 | -------------------------------------------------------------------------------- /man8/s6-permafailon.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-PERMAFAILON 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-permafailon 6 | .Nd read and analyse the death tally of a service (i.e. the recent process death events that happened), and if the death tally matches a given pattern, cause 7 | .Em permanent failure 8 | of the service, i.e. tells the supervisor not to try and restart it 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Ar secs 12 | .Ar deathcount 13 | .Ar events 14 | .Ar prog... 15 | .Sh DESCRIPTION 16 | .Nm 17 | is meant to be used in the 18 | .Pa ./finish 19 | script of a service directory supervised by 20 | .Xr s6-supervise 8 . 21 | .Pp 22 | .Nm 23 | must have the service directory of the tested service as its current 24 | directory. 25 | This is the default if it is called from the 26 | .Pa finish 27 | script of the service. 28 | .Pp 29 | It reads the death tally of the service, which is maintained by 30 | .Xr s6-supervise 8 . 31 | .Pp 32 | If the supervised process has died at least 33 | .Ar deathcount 34 | times in the last 35 | .Ar secs 36 | seconds with a cause listed in 37 | .Ar events , 38 | then 39 | .Nm 40 | exits 125. 41 | Else 42 | .Nm 43 | execs into 44 | .Ar prog... . 45 | .Pp 46 | .Ar events 47 | is a comma-separated list of events. 48 | An event can be one of the following: 49 | .Bl -bullet -width x 50 | .It 51 | An exit code, which is an integer between 0 and 255. 52 | Example: 53 | .Ql 1 . 54 | .It 55 | An exit code interval, which is two exit codes separated by a 56 | dash. 57 | Example: 58 | .Ql 1-50 . 59 | .It 60 | A signal name, or a signal number preceded by 61 | .Sq SIG . 62 | Examples: 63 | .Ql SIGTERM , 64 | .Ql sigabrt , 65 | .Ql sig11 . 66 | .El 67 | .Xr s6-supervise 8 68 | detects when the 69 | .Pa ./finish 70 | script of its service exits 125, and stops respawning the service. 71 | So, if the 72 | .Pa ./finish 73 | script is a chain-loading command line starting with a 74 | .Nm 75 | invocation (or containing such an invocation), when 76 | .Nm 77 | exits 125, then the 78 | .Pa ./finish 79 | script also exits 125 (because it is the same process), and the 80 | service is then marked as failing permanently. 81 | .Pp 82 | The 83 | .Pa ./finish 84 | script is 85 | .Em naturally 86 | a chain-loading command line if it is written in the execline[1] 87 | language. 88 | It can also be made into a chain-loading command line from a shell 89 | script by using 90 | .Ql exec s6-permafailon secs deathcount events rest-of-chainloading-cmdline... 91 | .Pp 92 | Multiple invocations of 93 | .Nm 94 | can be chained, in order to test several death patterns. 95 | .Pp 96 | If a permanent failure is triggered and 97 | .Ar secs 98 | is high, it is possible that when the administrator manually launches 99 | the service again, the next death triggers a permanent failure 100 | again. 101 | If this is not wanted, the administrator should clear the death tally 102 | with the 103 | .Xr s6-svdt-clear 8 104 | command. 105 | .Pp 106 | The current death tally can be viewed via the 107 | .Xr s6-svdt 8 108 | command. 109 | .Sh EXAMPLES 110 | .Dl s6-permafailon 60 5 1,101-103,SIGSEGV,SIGBUS prog... 111 | .Pp 112 | will exit 125 if the service has died 5 times in the last 60 seconds 113 | with an exit code of 1, 101, 102 or 103, a SIGSEGV or a SIGBUS. 114 | Else it will chainload into the 115 | .Ql prog... 116 | command line. 117 | .Sh SEE ALSO 118 | .Xr s6-notifyoncheck 8 , 119 | .Xr s6-supervise 8 , 120 | .Xr s6-svc 8 , 121 | .Xr s6-svdt 8 , 122 | .Xr s6-svdt-clear 8 , 123 | .Xr s6-svlisten 8 , 124 | .Xr s6-svlisten1 8 , 125 | .Xr s6-svok 8 , 126 | .Xr s6-svscan 8 , 127 | .Xr s6-svscanctl 8 , 128 | .Xr s6-svstat 8 , 129 | .Xr s6-svwait 8 130 | .Pp 131 | [1] 132 | .Lk https://skarnet.org/software/execline/ 133 | .Pp 134 | This man page is ported from the authoritative documentation at: 135 | .Lk https://skarnet.org/software/s6/s6-permafailon.html 136 | .Sh AUTHORS 137 | .An Laurent Bercot 138 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 139 | -------------------------------------------------------------------------------- /man8/s6-setlock.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SETLOCK 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-setlock 6 | .Nd take a lock on a file, then execute into another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl n | N | t Ar timeout 10 | .Op Fl r | w 11 | .Ar file 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | creates 16 | .Ar file 17 | if it does not exist and opens it for writing. 18 | .Pp 19 | It locks 20 | .Ar file . 21 | If it cannot take the lock for any reason, it exits 1. 22 | .Pp 23 | It executes into 24 | .Ar prog... . 25 | .Pp 26 | .Nm 27 | leaks an open file descriptor into the 28 | .Ar prog 29 | execution. 30 | This is intended: the fd holds the lock, which is released when 31 | .Ar prog 32 | exits. 33 | .Ar prog 34 | must not touch fds it does not know about. 35 | .Pp 36 | If the timed lock option is chosen, 37 | .Nm 38 | does not acquire the lock itself. 39 | Instead, it spawns an 40 | .Xr s6lockd-helper 8 41 | process that acquires the lock while 42 | .Nm 43 | controls the timeout; the 44 | .Xr s6lockd-helper 8 45 | process then holds the lock and lives as long as 46 | .Ar prog . 47 | .Sh OPTIONS 48 | .Bl -tag -width x 49 | .It Fl n 50 | Nonblocking lock. 51 | If 52 | .Nm 53 | cannot acquire the lock, it will exit 1 immediately. 54 | .It Fl N 55 | Blocking lock. 56 | .Nm 57 | will wait until it can acquire the lock. 58 | This is the default. 59 | .It Fl t Ar timeout 60 | Timed lock. 61 | If 62 | .Nm 63 | cannot acquire the lock after 64 | .Ar timeout 65 | milliseconds, it will exit 1. 66 | .It Fl r 67 | Shared lock. 68 | Other shared locks on the same file will not prevent the lock from 69 | being acquired (but an exclusive lock will). 70 | .It Fl w 71 | Exclusive lock. 72 | This is the default. 73 | .El 74 | .Sh SEE ALSO 75 | .Xr s6lockd 8 , 76 | .Xr s6lockd-helper 8 77 | .Pp 78 | This man page is ported from the authoritative documentation at: 79 | .Lk https://skarnet.org/software/s6/s6-setlock.html 80 | .Sh AUTHORS 81 | .An Laurent Bercot 82 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 83 | -------------------------------------------------------------------------------- /man8/s6-setsid.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SETSID 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-setsid 6 | .Nd run a program as a new session leader, or in a new foreground or background process group 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl s | b | f | g 10 | .Op Fl i | I | q 11 | .Op Fl d Ar ctty 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | creates a new session, or a new process group, and may make that 16 | process group the foreground process group, depending on the options 17 | it is run with. 18 | .Pp 19 | As session leader or process group leader, 20 | .Nm 21 | then executes into 22 | .Ar prog... . 23 | .Sh OPTIONS 24 | .Bl -tag -width x 25 | .It Fl s 26 | Session. 27 | .Nm 28 | will try and execute 29 | .Ar prog 30 | as a session leader. 31 | This is the default. 32 | .It Fl b 33 | Background process group. 34 | .Nm 35 | will not create a new session, but will create a new process group, 36 | and try and execute 37 | .Ar prog 38 | as the new process group leader. 39 | .It Fl f 40 | Foreground process group. 41 | .Nm 42 | will not create a new session, but will create a new process group and 43 | attach its session's controlling terminal to the new process group 44 | before executing 45 | .Ar prog . 46 | However, the new process group will likely be stopped, waiting for the 47 | former foreground process group to relinquish the controlling 48 | terminal, and will need to be sent a SIGCONT to resume. 49 | To avoid that, use the next option. 50 | .It Fl g 51 | Grab terminal. 52 | .Nm 53 | will not create a new session, but will create a new process group and 54 | attach its session's controlling terminal to the new process group 55 | before executing 56 | .Ar prog . 57 | It will forcefully grab the controlling terminal from the former 58 | foreground process group: a process belonging to that former 59 | foreground process group will be stopped if it attempts to read from 60 | or write to that terminal. 61 | .It Fl i 62 | Strict. 63 | If 64 | .Nm 65 | cannot perform the operations it needs, it will exit 111 with an error 66 | message. 67 | .It Fl I 68 | Loose. 69 | If 70 | .Nm 71 | cannot perform the operations, it will print a warning message, but 72 | exec into 73 | .Ar prog 74 | nonetheless. 75 | This is the default. 76 | .It Fl q 77 | Silent. 78 | .Nm 79 | will not print any warning message; it will exec into 80 | .Ar prog 81 | even if it cannot perform the operations. 82 | .It Fl d Ar ctty 83 | Assume file descriptor number 84 | .Ar ctty 85 | is the controlling terminal for the current session. 86 | Default is 0. 87 | This is only useful when used with the 88 | .Fl f 89 | or 90 | .Fl g 91 | options. 92 | .El 93 | .Sh SEE ALSO 94 | .Xr s6-applyuidgid 8 , 95 | .Xr s6-envdir 8 , 96 | .Xr s6-envuidgid 8 , 97 | .Xr s6-fghack 8 , 98 | .Xr s6-setuidgid 8 , 99 | .Xr s6-softlimit 8 , 100 | .Xr s6-tai64n 8 , 101 | .Xr s6-tai64nlocal 8 102 | .Pp 103 | This man page is ported from the authoritative documentation at: 104 | .Lk https://skarnet.org/software/s6/s6-setsid.html 105 | .Sh AUTHORS 106 | .An Laurent Bercot 107 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 108 | -------------------------------------------------------------------------------- /man8/s6-setuidgid.8: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt S6-SETUIDGID 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-setuidgid 6 | .Nd execute a program as another user 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar account 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | If 13 | .Ar account 14 | is the empty string, then 15 | .Nm 16 | directly 17 | .Xr exec 3 Ns 18 | s into 19 | .Ar prog... 20 | without any state changes. 21 | If 22 | .Ar account 23 | contains a colon, it is interpreted as 24 | .Sm off 25 | .So 26 | .Em uid : 27 | .Em gid 28 | .Sc 29 | .Sm on , 30 | else it is interpreted as a username and looked up by name in the 31 | account database. 32 | .Pp 33 | If 34 | .Ar account 35 | is unknown, 36 | .Nm 37 | exits 1. 38 | .Nm 39 | sets its (real and effective) uid and gid to those of 40 | .Ar account . 41 | It also sets the list of supplementary groups to the correct one for 42 | .Ar account 43 | according to the group database. 44 | .Pp 45 | Then it executes into 46 | .Ar prog... . 47 | .Pp 48 | Unless 49 | .Ar account 50 | is empty, 51 | .Nm 52 | can only be run as root. 53 | Its main use is to drop root privileges before starting a daemon. 54 | .Sh SEE ALSO 55 | .Xr s6-applyuidgid 8 , 56 | .Xr s6-envdir 8 , 57 | .Xr s6-envuidgid 8 , 58 | .Xr s6-fghack 8 , 59 | .Xr s6-setsid 8 , 60 | .Xr s6-softlimit 8 , 61 | .Xr s6-tai64n 8 , 62 | .Xr s6-tai64nlocal 8 63 | .Pp 64 | This man page is ported from the authoritative documentation at: 65 | .Lk https://skarnet.org/software/s6/s6-setuidgid.html 66 | .Sh AUTHORS 67 | .An Laurent Bercot 68 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 69 | -------------------------------------------------------------------------------- /man8/s6-socklog.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SOCKLOG 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-socklog 6 | .Nd minimal syslog daemon 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl d Ar notif 10 | .Op Fl r 11 | .Op Fl U | Fl u Ar uid Fl g Ar gid Fl G Ar gidlist 12 | .Op Fl l Ar linelen 13 | .Op Fl t Ar lameducktimeout 14 | .Op Fl x Ar unixsocket | Fl i Ar ipport 15 | .Sh DESCRIPTION 16 | .Nm 17 | is a reimplementation of the 18 | .Xr socklog 8 19 | program with a few more features. 20 | .Pp 21 | .Nm 22 | reads datagrams from the 23 | .Pa /dev/log 24 | Unix domain socket, or from a Unix domain or Internet domain socket of 25 | the user's choice, converts the encoded syslog facility and priority 26 | names to their human-readable equivalents, and prints the logs to its 27 | stdout. 28 | .Bl -bullet -width x 29 | .It 30 | .Nm 31 | binds to 32 | .Pa /dev/log . 33 | .It 34 | It drops its root privileges. 35 | .It 36 | For every datagram it reads, it turns its content into a log line: 37 | .Bl -bullet -width x 38 | .It 39 | Messages are truncated to 1024 characters. 40 | .It 41 | Trailing nulls or newlines are removed. 42 | .It 43 | Embedded nulls or newlines are converted to 44 | .Ql ~ 45 | characters (tildes). 46 | .It 47 | A 48 | .Ql syslogcode 49 | at the beginning of the line is converted to 50 | .Ql facility.priority:\ \& . 51 | .El 52 | .It 53 | It prints the log line to its stdout, terminated by a newline. 54 | .It 55 | It exits 0 on a SIGTERM. 56 | .El 57 | .Ss Signals 58 | .Nm 59 | reacts to the following signals: 60 | .Bl -tag -width x 61 | .It SIGTERM 62 | Exit as soon as possible. 63 | .El 64 | .Ss Typical use 65 | .Nm 66 | can be paired with 67 | .Xr s6-log 8 68 | to implement 69 | .Ql syslogd 70 | functionality. 71 | .Nm 72 | acts as the 73 | .Em frontend : 74 | it reads the log lines and processes them, then pipes them 75 | to an 76 | .Xr s6-log 8 77 | instance that acts as the 78 | .Em backend , 79 | i.e. sorts the log lines depending on regular expressions that 80 | typically involve the facility and priority names, then stores them 81 | into the filesystem. 82 | .Pp 83 | The pipe between 84 | .Nm 85 | and 86 | .Xr s6-log 8 87 | is typically a 88 | .Em logging pipe 89 | automatically provided by 90 | .Xr s6-svscan 8 91 | when the 92 | .Xr s6-log 8 93 | instance is declared as a logger service for the 94 | .Nm 95 | instance. 96 | .Pp 97 | The 98 | .Pa examples/ 99 | subdirectory of the s6 package contains a turnkey 100 | .Ql syslogd 101 | service that implements this pattern. 102 | .Pp 103 | .Nm 104 | cannot be used under 105 | .Xr s6-ipcserver 8 106 | or another super-server. 107 | It does not implement the 108 | .Sq socklog ucspi functionality , 109 | which is provided by the 110 | .Xr ucspilogd 8 111 | program instead. 112 | .Sh OPTIONS 113 | .Bl -tag -width x 114 | .It Fl r 115 | Raw logging. 116 | .Ql 117 | codes will not be converted to facility/priority names. 118 | .It Fl d Ar notif 119 | When ready (actually bound to its socket), write a newline to file 120 | descriptor 121 | .Ar notif 122 | then close it. 123 | This allows 124 | .Nm 125 | to use the 126 | .Xr s6-notifywhenup 7 127 | mechanism to notify readiness. 128 | .Ar notif 129 | cannot be less than 3. 130 | If this option is not given, no readiness notification is sent. 131 | .It Fl u Ar uid 132 | Drop user id to 133 | .Ar id . 134 | .It Fl g Ar gid 135 | Drop group id to 136 | .Ar gid . 137 | .It Fl G Ar gidlist 138 | Set supplementary group list to 139 | .Ar gidlist , 140 | which must be given as a comma-separated list of numeric gids, without 141 | spaces. 142 | .It Fl U 143 | Set user id, group id and supplementary group list to the values of 144 | the 145 | .Ev UID , 146 | .Ev GID 147 | and 148 | .Ev GIDLIST 149 | environment variables. 150 | If a 151 | .Fl u , 152 | .Fl g 153 | or 154 | .Fl G 155 | option is given after 156 | .Fl U , 157 | the command line value overrides the environment variable. 158 | .It Fl l Ar linelen 159 | Set the maximum datagram size to 160 | .Ar linelen . 161 | Default is 1024. 162 | It cannot be set to less than 80 or more than 1048576. 163 | If a datagram is bigger than 164 | .Ar linelen , 165 | it will be truncated to 166 | .Ar linelen 167 | characters, and the logged line will end with a 168 | .Ql ... 169 | ellipsis to show the truncation. 170 | .It Fl t Ar lameducktimeout 171 | On receipt of a 172 | .Dv SIGTERM , 173 | give 174 | .Nm 175 | a grace period of 176 | .Ar lameducktimeout 177 | milliseconds to flush any log lines that are still in its buffer. 178 | Default is 0, which means infinite: the program will only exit when 179 | its buffer is empty, and may wait forever. 180 | If 181 | .Ar lameducktimeout 182 | is nonzero and the timeout expires, the program will exit 99. 183 | .It Fl x Ar unixsocket 184 | Bind to a Unix domain socket at 185 | .Ar unixsocket . 186 | Default is 187 | .Pa /dev/log . 188 | .It Fl i Ar ipport 189 | Bind to a UDP socket. 190 | .Ar ipport 191 | is a combination of 192 | .Ar ip , 193 | which must be an IPv4 or IPv6 address, and 194 | .Ar port , 195 | which must be an integer. 196 | .Ar port 197 | may be omitted, in which case it defaults to 514. 198 | If 199 | .Ar port 200 | is given, 201 | .Ar ip 202 | and 203 | .Ar port 204 | must be separated by a 205 | .Ql _ 206 | character (an underscore). 207 | If 208 | .Ar ip 209 | is IPv4, a 210 | .Ql \&: 211 | (colon) can be used instead of an underscore. 212 | When this option is used, 213 | .Nm 214 | will prepend every log line with 215 | .Sq Ar clientip Ns _ Ns Ar clientport:\ \& , 216 | .Ar clientip 217 | and 218 | .Ar clientport 219 | being the IP address and port of the client that sent the log 220 | datagram. 221 | .El 222 | .Sh EXIT STATUS 223 | .Bl -tag -width x 224 | .It 0 225 | .Dv SIGTERM 226 | received, clean exit. 227 | .It 99 228 | .Dv SIGTERM 229 | received but the buffer could not be flushed in time, some logs may be 230 | lost. 231 | .It 100 232 | Wrong usage. 233 | .It 111 234 | System call failed. 235 | .El 236 | .Sh SEE ALSO 237 | .Xr s6-ipcserver 8 , 238 | .Xr s6-log 8 , 239 | .Xr s6-svscan 8 , 240 | .Xr socklog 8 , 241 | .Xr ucspilogd 8 242 | .Pp 243 | This man page is ported from the authoritative documentation at: 244 | .Lk https://skarnet.org/software/s6/s6-socklog.html 245 | .Sh AUTHORS 246 | .An Laurent Bercot 247 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 248 | -------------------------------------------------------------------------------- /man8/s6-softlimit.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SOFTLIMIT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-softlimit 6 | .Nd change process limits, then execute into another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl a Ar allmem 10 | .Op Fl c Ar core 11 | .Op Fl d Ar data 12 | .Op Fl f Ar fsize 13 | .Op Fl l Ar lock 14 | .Op Fl m Ar mem 15 | .Op Fl o Ar ofiles 16 | .Op Fl p Ar proc 17 | .Op Fl r Ar res 18 | .Op Fl s Ar stack 19 | .Op Fl t Ar cpusecs 20 | .Ar prog... 21 | .Sh DESCRIPTION 22 | .Nm 23 | parses its options and sets process (soft) resource limits accordingly. 24 | .Pp 25 | A value of 26 | .Ql = 27 | for any option means 28 | .Dq set that limit to the hard limit . 29 | .Pp 30 | Depending on your operating system, an option may do nothing. 31 | .Pp 32 | When 33 | .Nm 34 | has modified all the limits successfully, it executes into 35 | .Ar prog... . 36 | .Sh OPTIONS 37 | .Bl -tag -width x 38 | .It Fl a Ar allmem 39 | Limit the total available memory to 40 | .Ar allmem 41 | bytes. 42 | .It Fl c Ar core 43 | Limit the core file size to 44 | .Ar core 45 | bytes. 46 | .It Fl d Ar data 47 | Limit the available heap memory to 48 | .Ar data 49 | bytes. 50 | .It Fl f Ar fsize 51 | Limit the file size to 52 | .Ar fsize 53 | bytes. 54 | .It Fl l Ar lock 55 | Limit the available locked memory to 56 | .Ar lock 57 | bytes. 58 | .It Fl m Ar mem 59 | Limit all types of memory to 60 | .Ar mem 61 | bytes. 62 | .It Fl o Ar ofiles 63 | Limit the number of open fds to 64 | .Ar ofiles . 65 | .It Fl p Ar proc 66 | Limit the number of processes to 67 | .Ar proc 68 | (per user). 69 | .It Fl r Ar res 70 | Limit the available physical memory to 71 | .Ar res 72 | bytes. 73 | .It Fl s Ar stack 74 | Limit the available stack memory to 75 | .Ar stack 76 | bytes. 77 | .It Fl t Ar cpusecs 78 | Limit the available CPU time to 79 | .Ar cpusecs 80 | seconds. 81 | .El 82 | .Sh SEE ALSO 83 | .Xr s6-applyuidgid 8 , 84 | .Xr s6-envdir 8 , 85 | .Xr s6-envuidgid 8 , 86 | .Xr s6-fghack 8 , 87 | .Xr s6-setsid 8 , 88 | .Xr s6-setuidgid 8 , 89 | .Xr s6-tai64n 8 , 90 | .Xr s6-tai64nlocal 8 91 | .Pp 92 | This man page is ported from the authoritative documentation at: 93 | .Lk https://skarnet.org/software/s6/s6-softlimit.html 94 | .Sh AUTHORS 95 | .An Laurent Bercot 96 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 97 | -------------------------------------------------------------------------------- /man8/s6-sudo.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SUDO 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-sudo 6 | .Nd connect to a Unix domain socket and pass its standard file descriptors, command-line arguments and environment to a program running on the server side, potentially with different privileges 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl q | Q | v 10 | .Op Fl p Ar bindpath 11 | .Op Fl l Ar localname 12 | .Op Fl e 13 | .Op Fl t Ar timeoutconn 14 | .Op Fl T Ar timeoutrun 15 | .Ar path 16 | .Op Ar args... 17 | .Sh DESCRIPTION 18 | .Nm 19 | executes into 20 | .Xr s6-ipcclient 8 21 | .Ar path 22 | .Xr s6-sudoc 8 23 | .Ar args... . 24 | It does nothing else: it is just a convenience program. 25 | The 26 | .Xr s6-ipcclient 8 27 | program connects to a Unix socket at 28 | .Ar path , 29 | and the 30 | .Xr s6-sudoc 8 31 | program transmits the desired elements over the socket. 32 | .Pp 33 | It should be used to connect to an 34 | .Xr s6-local-service 7 35 | running the 36 | .Xr s6-sudod 8 37 | program, which will run a server program on the client's behalf. 38 | .Sh OPTIONS 39 | The 40 | .Fl q , 41 | .Fl Q , 42 | .Fl v , 43 | .Fl p 44 | and 45 | .Fl l 46 | options are passed to 47 | .Xr s6-ipcclient 8 . 48 | .Pp 49 | The 50 | .Fl e , 51 | .Fl t 52 | and 53 | .Fl T 54 | options are passed to 55 | .Xr s6-sudoc 8 . 56 | .Pp 57 | Command-line arguments, if any, are also passed to 58 | .Xr s6-sudoc 8 , 59 | which will transmit them to 60 | .Xr s6-sudod 8 61 | over the socket. 62 | .Sh SEE ALSO 63 | .Xr s6-sudoc 8 , 64 | .Xr s6-sudod 8 65 | .Pp 66 | This man page is ported from the authoritative documentation at: 67 | .Lk https://skarnet.org/software/s6/s6-sudo.html 68 | .Sh AUTHORS 69 | .An Laurent Bercot 70 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 71 | -------------------------------------------------------------------------------- /man8/s6-sudoc.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SUDOC 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-sudoc 6 | .Nd talk to a peer 7 | .Xr s6-sudod 8 8 | program over a Unix socket, passing it command-line arguments, 9 | environment variables and standard descriptors 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl e 13 | .Op Fl t Ar timeoutconn 14 | .Op Fl T Ar timeoutrun 15 | .Op Ar args... 16 | .Sh DESCRIPTION 17 | .Nm 18 | transmits its standard input, standard output and standard error via 19 | fd-passing over a Unix socket that must be open on its descriptors 6 20 | and 7. 21 | It expects an 22 | .Xr s6-sudod 8 23 | process to be receiving them on the other side. 24 | .Pp 25 | It also transmits its command-line arguments 26 | .Ar args... , 27 | and also its environment by default. 28 | Note that 29 | .Xr s6-sudod 8 30 | will not necessarily accept all the environment variables that 31 | .Nm 32 | tries to transmit. 33 | .Pp 34 | .Nm 35 | waits for the server program run by 36 | .Xr s6-sudod 8 37 | to finish. 38 | It exits the same exit code as the server program. 39 | If the server program is killed by a signal, 40 | .Nm 41 | kills itself with the same signal. 42 | .Pp 43 | If 44 | .Nm 45 | is killed, or exits after 46 | .Ar timeoutrun 47 | milliseconds, while the server program is still running, 48 | .Xr s6-sudod 8 49 | will send a SIGTERM and a SIGCONT to the server program - but this 50 | does not guarantee that it will die. 51 | If the server program keeps running, it might still read from the file 52 | that was 53 | .Nm Ap 54 | s stdin, or write to the files that were 55 | .Nm Ap 56 | s stdout or stderr. 57 | .Sy This is a potential security risk. 58 | Administrators should audit their server programs to make sure this 59 | does not happen. 60 | .Pp 61 | More generally, anything using signals or terminals will not be 62 | handled transparently by the 63 | .Nm 64 | + 65 | .Xr s6-sudod 8 66 | mechanism. 67 | The mechanism was designed to allow programs to gain privileges in 68 | specific situations: short-lived, simple, noninteractive processes. 69 | It was not designed to emulate the full suid functionality and will 70 | not go out of its way to do so. 71 | .Sh OPTIONS 72 | .Bl -tag -width x 73 | .It Fl e 74 | Do not attempt to transmit any environment variables to 75 | .Xr s6-sudod 8 . 76 | .It Fl t Ar timeoutconn 77 | If 78 | .Xr s6-sudod 8 79 | has not managed to process the given information and start the server 80 | program after 81 | .Ar timeoutconn 82 | milliseconds, give up. 83 | By default, 84 | .Ar timeoutconn 85 | is 0, meaning infinite. 86 | Note that there is no reason to set up a nonzero 87 | .Ar timeoutconn 88 | with a large value: 89 | .Xr s6-sudod 8 90 | is not supposed to block. 91 | The option is only there to protect against ill-written services. 92 | .It Fl T Ar timeoutrun 93 | If the server program has not exited after 94 | .Ar timeoutrun 95 | milliseconds, give up. 96 | By default, 97 | .Ar timeoutrun 98 | is 0, meaning infinite. 99 | .El 100 | .Sh SEE ALSO 101 | .Xr s6-sudo 8 , 102 | .Xr s6-sudod 8 103 | .Pp 104 | This man page is ported from the authoritative documentation at: 105 | .Lk https://skarnet.org/software/s6/s6-sudoc.html 106 | .Sh AUTHORS 107 | .An Laurent Bercot 108 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 109 | -------------------------------------------------------------------------------- /man8/s6-svdt-clear.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVDT-CLEAR 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svdt-clear 6 | .Nd clear the recorded death tally of a service 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar servicedir 10 | .Sh DESCRIPTION 11 | .Nm 12 | clears the recorded death tally of the service being currently 13 | supervised at the 14 | .Ar servicedir 15 | .Xr s6-service-directory 7 . 16 | .Pp 17 | Use of 18 | .Nm 19 | impacts the listings obtained by the 20 | .Xr s6-svdt 8 21 | command. 22 | .Pp 23 | It also impacts the behaviour of the 24 | .Xr s6-permafailon 8 25 | command. 26 | This is the main reason to use 27 | .Nm : 28 | once a service has failed permanently due to an excessive number of 29 | deaths in a given time, it can be useful to erase that record of 30 | deaths before starting the service again, in order to avoid 31 | permanently failing again too fast. 32 | .Sh EXIT STATUS 33 | .Bl -tag -width x 34 | .It 0 35 | Success. 36 | .It 100 37 | Wrong usage. 38 | .It 111 39 | System call failed. 40 | .El 41 | .Sh SEE ALSO 42 | .Xr s6-notifyoncheck 8 , 43 | .Xr s6-permafailon 8 , 44 | .Xr s6-supervise 8 , 45 | .Xr s6-svc 8 , 46 | .Xr s6-svdt 8 , 47 | .Xr s6-svlisten 8 , 48 | .Xr s6-svlisten1 8 , 49 | .Xr s6-svok 8 , 50 | .Xr s6-svscan 8 , 51 | .Xr s6-svscanctl 8 , 52 | .Xr s6-svstat 8 , 53 | .Xr s6-svwait 8 54 | .Pp 55 | This man page is ported from the authoritative documentation at: 56 | .Lk https://skarnet.org/software/s6/s6-svdt-clear.html 57 | .Sh AUTHORS 58 | .An Laurent Bercot 59 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 60 | -------------------------------------------------------------------------------- /man8/s6-svdt.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVDT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svdt 6 | .Nd print the recorded death tally of a service, i.e. a list of the times the process died, with the cause of death 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl S | s 10 | .Op Fl n Ar maxlines 11 | .Ar servicedir 12 | .Sh DESCRIPTION 13 | .Nm 14 | prints the contents of the recorded death tally of the service being 15 | currently supervised at the 16 | .Ar servicedir 17 | .Xr s6-service-directory 7 , 18 | then exits 0. 19 | .Pp 20 | For each recorded death, 21 | .Nm 22 | prints one line. 23 | This line contains the following fields, separated with spaces: 24 | .Bl -bullet -width x 25 | .It 26 | A TAI64N[1] timestamp. 27 | .It 28 | The word 29 | .Sq signal 30 | if the death was caused by a signal, or the word 31 | .Sq exitcode 32 | if the death was a normal exit. 33 | .It 34 | The name of the signal that caused the death, or the exit code of the 35 | process. 36 | .El 37 | .Pp 38 | To obtain human-readable local time or GMT time instead of TAI64N 39 | timestamps, simply pipe 40 | .Nm Ap 41 | s output into 42 | .Xr s6-tai64nlocal 8 . 43 | .Pp 44 | Process deaths are recorded up to a default maximum of 100. 45 | This default can be modified via the 46 | .Pa max-death-tally 47 | file in the 48 | .Xr s6-service-directory 7 . 49 | .Sh OPTIONS 50 | .Bl -tag -width x 51 | .It Fl S 52 | Print signal names. 53 | This is the default. 54 | .It Fl s 55 | Print signal numbers. 56 | The numerical value of the signal will be printed instead of the 57 | signal name. 58 | .It Fl n Ar maxlines 59 | Limit the output to at most the latest 60 | .Ar maxlines 61 | deaths. 62 | .El 63 | .Sh EXIT STATUS 64 | .Bl -tag -width x 65 | .It 0 66 | Success. 67 | .It 100 68 | Wrong usage. 69 | .It 111 70 | System call failed. 71 | .El 72 | .Sh SEE ALSO 73 | .Xr s6-notifyoncheck 8 , 74 | .Xr s6-permafailon 8 , 75 | .Xr s6-supervise 8 , 76 | .Xr s6-svc 8 , 77 | .Xr s6-svdt-clear 8 , 78 | .Xr s6-svlisten 8 , 79 | .Xr s6-svlisten1 8 , 80 | .Xr s6-svok 8 , 81 | .Xr s6-svscan 8 , 82 | .Xr s6-svscanctl 8 , 83 | .Xr s6-svstat 8 , 84 | .Xr s6-svwait 8 85 | .Pp 86 | [1] 87 | .Lk https://cr.yp.to/daemontools/tai64n.html 88 | .Pp 89 | This man page is ported from the authoritative documentation at: 90 | .Lk https://skarnet.org/software/s6/s6-svdt.html 91 | .Sh AUTHORS 92 | .An Laurent Bercot 93 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 94 | -------------------------------------------------------------------------------- /man8/s6-svlink.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVLINK 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svlink 6 | .Nd integrate service directories into an existing service manager sequence and eliminate race conditions 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl d | Fl D 10 | .Op Fl P 11 | .Op Fl f 12 | .Op Fl t Ar timeout 13 | .Ar scandir 14 | .Ar servicedir 15 | .Op Ar name 16 | .Sh DESCRIPTION 17 | .Nm 18 | creates, in an 19 | .Xr s6-scan-directory 7 , 20 | a symlink to an 21 | .Xr s6-service-directory 7 , 22 | and notifies 23 | .Xr s6-svscan 8 24 | that a new service has been registered. 25 | It waits until an 26 | .Xr s6-supervise 8 27 | supervisor process has been spawned to manage the new service, then exits. 28 | .Bl -bullet -width x 29 | .It 30 | .Nm 31 | expects a running 32 | .Xr s6-svscan 8 33 | process on 34 | .Ar scandir 35 | and a fully functional, but unsupervised, 36 | .Xr s6-service-directory 7 37 | in 38 | .Ar servicedir . 39 | .It 40 | It symlinks 41 | .Ar servicedir 42 | into 43 | .Ar scandir . 44 | The symbolic link is named 45 | .Ar name ; 46 | if no 47 | .Ar name 48 | argument has been given, the name given to the symbolic link is the 49 | basename of 50 | .Ar servicedir . 51 | .It 52 | It sends a command to 53 | .Xr s6-svscan 8 54 | to signal it that a new service is available. 55 | .It 56 | It waits for an 57 | .Xr s6-supervise 8 58 | process to be spawned on 59 | .Ar servicedir . 60 | .It 61 | It exits 0. 62 | .El 63 | .Pp 64 | Using 65 | .Nm 66 | to start services is a suboptimal pattern: it requires precise 67 | manipulations involving use of 68 | .Xr s6-ftrigrd 8 69 | in order to avoid race conditions, so it is relatively expensive. 70 | The simpler, more efficient pattern is to have all the supervisors 71 | already started at boot time, so the existence of the supervisor can 72 | be relied on, and starting the service becomes a trival and instant 73 | operation - this is, for instance, how the s6-rc service manager[1] 74 | behaves. 75 | However, it can be difficult to implement this pattern with other 76 | services managers such as OpenRC; in those cases, 77 | .Nm , 78 | which starts the supervisors one at a time, can be used instead. 79 | .Pp 80 | If 81 | .Ar servicedir 82 | is logged, i.e.\& 83 | .Ql Pa servicedir Ns /log 84 | is also a valid service directory, then 85 | .Nm 86 | will wait until supervisors have been spawned for both the service and 87 | its logger. 88 | .Pp 89 | .Nm 90 | sends an 91 | .Ql s6-svscanctl -a 92 | command to 93 | .Ar scandir , 94 | which means that the system's view of services will be refreshed. 95 | Depending on what links exist in 96 | .Ar scandir , 97 | other services than 98 | .Ar servicedir 99 | may also appear. 100 | .Pp 101 | The symmetrical program to 102 | .Nm 103 | is named 104 | .Xr s6-svunlink 8 . 105 | .Sh OPTIONS 106 | .Bl -tag -width x 107 | .It Fl d 108 | Down. 109 | The supervisor will be started, but the service itself will remain down. 110 | Any 111 | .Ql Pa servicedir Ns /down 112 | file will be deleted. 113 | By default, if neither the 114 | .Fl d 115 | nor 116 | .Fl D 117 | options have been given, the supervisor auto-starts the service as 118 | soon as it runs. 119 | .It Fl D 120 | Down, and stay down. 121 | The supervisor will be started, but the service itself will remain down. 122 | A 123 | .Ql Pa servicedir Ns /down 124 | file will be created. 125 | By default, if neither the 126 | .Fl d 127 | nor 128 | .Fl D 129 | options have been given, the supervisor auto-starts the service as 130 | soon as it runs. 131 | .It Fl P 132 | Public. 133 | If 134 | .Ql Pa servicedir Ns /event 135 | does not exist, it will be created as public, i.e. anyone will be able 136 | to subscribe to this 137 | .Xr s6-fifodir 7 . 138 | By default, it will be created as private, i.e. only processes running 139 | with the same gid as the 140 | .Xr s6-svscan 8 141 | process will be able to subscribe to it. 142 | .It Fl f 143 | Force permissions. 144 | The presence or absence of the 145 | .Fl P 146 | option (i.e. the public or private state of 147 | .Ql Pa servicedir Ns /event ) 148 | will be enforced even if 149 | .Ql Pa servicedir Ns /event 150 | already exists. 151 | By default, 152 | .Nm 153 | exits with an error message if 154 | .Ql Pa servicedir Ns /event 155 | exists and its public/private state mismatches what is requested. 156 | .It Fl t Ar timeout 157 | If the supervisor has not started after 158 | .Ar timeout 159 | milliseconds, 160 | .Nm 161 | will print a message to stderr and exit 99. 162 | By default, 163 | .Ar timeout 164 | is 0, which means no time limit. 165 | .El 166 | .Sh EXIT STATUS 167 | .Bl -tag -width x 168 | .It 0 169 | Success. 170 | .It 99 171 | Timeout while waiting for the supervisor to start. 172 | .It 100 173 | Wrong usage. 174 | .It 111 175 | System call failed. 176 | .El 177 | .Sh SEE ALSO 178 | .Xr s6-fifodir 7 , 179 | .Xr s6-scan-directory 7 , 180 | .Xr s6-service-directory 7 , 181 | .Xr s6-ftrigrd 8 , 182 | .Xr s6-supervise 8 , 183 | .Xr s6-svscan 8 , 184 | .Xr s6-svscanctl 8 , 185 | .Xr s6-svunlink 8 186 | .Pp 187 | [1] 188 | .Lk https://skarnet.org/software/s6-rc/ 189 | .Pp 190 | This man page is ported from the authoritative documentation at: 191 | .Lk https://skarnet.org/software/s6/s6-svlink.html 192 | .Sh AUTHORS 193 | .An Laurent Bercot 194 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 195 | -------------------------------------------------------------------------------- /man8/s6-svlisten.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVLISTEN 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svlisten 6 | .Nd run a program while listening on notifications from a collection of supervised services, and block until they all go up, or down 7 | .Sh SYNOPSIS 8 | .Bl -bullet -width x 9 | .It 10 | In an execline[1] script: 11 | .Pp 12 | .Nm 13 | .Op Fl U | u | D | d | r | R 14 | .Op Fl a | o 15 | .Op Fl t Ar timeout 16 | .Bro 17 | .Ar servicedir servicedir... 18 | .Brc 19 | .Ar prog... 20 | .It 21 | Outside of an execline script: 22 | .Pp 23 | .Nm 24 | .Op Fl U | u | D | d | r | R 25 | .Op Fl a | o 26 | .Op Fl t Ar timeout 27 | .Ar servicedir servicedir... 28 | "" 29 | .Ar prog... 30 | .El 31 | .Sh DESCRIPTION 32 | .Nm 33 | only waits for notifications; it never polls. 34 | .Pp 35 | .Nm 36 | checks the state of one or more 37 | .Xr s6-service-directory 7 Ns s 38 | given as arguments in the first block and monitors their state 39 | changes. 40 | .Pp 41 | It spawns 42 | .Ar prog... 43 | as a child right after getting the initial state of all the monitored 44 | services. 45 | .Pp 46 | It then blocks until the wanted state happens. 47 | .Pp 48 | .Nm 49 | is the service-specific version of 50 | .Xr s6-ftrig-listen 8 . 51 | The point of 52 | .Nm s6-svlisten 53 | is to use it to spawn a program such as 54 | .Xr s6-svc 8 , 55 | in order to send signals to services while making sure to catch their 56 | state changes - thus avoiding the race condition that occurs when 57 | running 58 | .Xr s6-svc 8 59 | then 60 | .Xr s6-svwait 8 61 | sequentially. 62 | .Pp 63 | .Nm 64 | needs to handle a variable length list of service directories. 65 | For that, it uses an encoding provided by execline, so it's best to 66 | only use it in execline scripts (only the execline syntax is 67 | guaranteed not to change). 68 | There is a variant of 69 | .Nm 70 | that does not use execline syntax, but only handles one service 71 | directory: 72 | .Xr s6-svlisten1 8 . 73 | .Pp 74 | The 75 | .Fl R 76 | or 77 | .Fl r 78 | options imply the 79 | .Fl a 80 | option. 81 | It is not possible to wait for one of the listed services to restart. 82 | .Sh OPTIONS 83 | .Bl -tag -width x 84 | .It Fl u 85 | Up. 86 | .Nm 87 | will wait until the services are up, as reported by 88 | .Xr s6-supervise 8 . 89 | This is the default; it is not reliable, but it does not depend on 90 | specific support in the service programs. 91 | See 92 | .Xr s6-notifywhenup 7 93 | for details. 94 | .It Fl U 95 | Really up. 96 | .Nm 97 | will wait until the services are up and ready as reported by the 98 | services themselves. 99 | This requires specific support in the service programs, and the use of 100 | the 101 | .Pa notification-fd 102 | file in the service directory. 103 | See the explanation in 104 | .Xr s6-notifywhenup 7 . 105 | .It Fl d 106 | Down. 107 | .Nm 108 | will wait until the services are down. 109 | .It Fl D 110 | Really down. 111 | .Nm 112 | will wait until the services are down and the cleanup scripts in 113 | .Sm off 114 | .Ar servicedir / 115 | .Pa finish 116 | .Sm on for every 117 | .Ar servicedir 118 | have finished executing (or have timed out and been killed). 119 | .It Fl r 120 | Restart. 121 | .Nm 122 | will wait until all the services have been started or restarted, 123 | i.e. they have been in the down state, then the up state. 124 | .It Fl R 125 | Restart and ready. 126 | .Nm 127 | will wait until all the services have been started or restarted and 128 | have notified readiness. 129 | .It Fl o 130 | Or. 131 | .Nm 132 | will wait until one of the given services comes up or down. 133 | .It Fl a 134 | And. 135 | .Nm 136 | will wait until all of the given services come up or down. 137 | This is the default. 138 | .It Fl t Ar timeout 139 | If the requested events have not happened after 140 | .Ar timeout 141 | milliseconds, 142 | .Nm 143 | will print a message to stderr and exit 99. 144 | By default, 145 | .Ar timeout 146 | is 0, which means no time limit. 147 | .El 148 | .Sh EXIT STATUS 149 | .Bl -tag -width x 150 | .It 0 151 | Success, the wanted state has been reached. 152 | .It 99 153 | Timed out. 154 | .It 100 155 | Wrong usage. 156 | .It 102 157 | The 158 | .Xr s6-supervise 8 159 | process monitoring the service died. 160 | .It 111 161 | System call failed. 162 | .It Em n 163 | Services were expected to come up, but 164 | .Em n 165 | of them reported permanent failure. 166 | .El 167 | .Sh SEE ALSO 168 | .Xr s6-notifyoncheck 8 , 169 | .Xr s6-permafailon 8 , 170 | .Xr s6-supervise 8 , 171 | .Xr s6-svc 8 , 172 | .Xr s6-svdt 8 , 173 | .Xr s6-svdt-clear 8 , 174 | .Xr s6-svlisten1 8 , 175 | .Xr s6-svok 8 , 176 | .Xr s6-svscan 8 , 177 | .Xr s6-svscanctl 8 , 178 | .Xr s6-svstat 8 , 179 | .Xr s6-svwait 8 180 | .Pp 181 | [1] 182 | .Lk https://skarnet.org/software/execline/ 183 | .Pp 184 | This man page is ported from the authoritative documentation at: 185 | .Lk https://skarnet.org/software/s6/s6-svlisten.html 186 | .Sh AUTHORS 187 | .An Laurent Bercot 188 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 189 | -------------------------------------------------------------------------------- /man8/s6-svlisten1.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVLISTEN1 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svlisten1 6 | .Nd run a program while listening on notifications from a supervised service, and block until said service goes up, or down 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl U | u | D | d | r | R 10 | .Op Fl t Ar timeout 11 | .Ar servicedir 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | only waits for notifications; it never polls. 16 | .Nm 17 | checks the state of the 18 | .Ar servicedir 19 | .Xr s6-service-directory 7 20 | and monitors its state changes. 21 | .Pp 22 | It spawns 23 | .Ar prog... 24 | as a child right after getting the initial state of the service. 25 | .Pp 26 | It then blocks until the wanted state happens. 27 | .Pp 28 | .Nm 29 | is the service-specific version of 30 | .Xr s6-ftrig-listen1 8 . 31 | The point of 32 | .Nm 33 | is to use it to spawn a program such as 34 | .Xr s6-svc 8 , 35 | in order to send signals to a service while making sure to catch its 36 | state changes - thus avoiding the race condition that occurs when 37 | running 38 | .Xr s6-svc 8 39 | then 40 | .Xr s6-svwait 8 41 | sequentially. 42 | .Pp 43 | The 44 | .Xr s6-svlisten 8 45 | program is an extension of 46 | .Nm . 47 | It can watch the state of several services at once; however, its 48 | syntax makes it best used in execline[1] scripts only. 49 | .Sh OPTIONS 50 | .Bl -tag -width x 51 | .It Fl u 52 | Up. 53 | .Nm 54 | will wait until the service is up, as reported by 55 | .Xr s6-supervise 8 . 56 | This is the default; it is not reliable, but it does not depend on 57 | specific support in the service programs. 58 | See 59 | .Xr s6-notifywhenup 7 60 | for details. 61 | .It Fl U 62 | Really up. 63 | .Nm 64 | will wait until the service is up and ready as reported by the daemon 65 | itself. 66 | This requires specific support in the service programs, and the use of 67 | the 68 | .Pa notification-fd 69 | file in the 70 | .Xr s6-service-directory 7 . 71 | See the explanation in 72 | .Xr s6-notifywhenup 7 . 73 | .It Fl d 74 | Down. 75 | .Nm 76 | will wait until the service is down. 77 | .It Fl D 78 | Really down. 79 | .Nm 80 | will wait until the service is down and the cleanup script in 81 | .Sm off 82 | .Ar servicedir / 83 | .Pa finish 84 | .Sm on 85 | has finished executing (or has timed out and been killed). 86 | .It Fl r 87 | Restart. 88 | .Nm 89 | will wait until the service has been started or restarted, i.e. they 90 | have been in the down state, then the up state. 91 | .It Fl R 92 | Restart and ready. 93 | .Nm 94 | will wait until the service has been started or restarted and has 95 | notified readiness. 96 | .It Fl t Ar timeout 97 | If the requested event has not happened after 98 | .Ar timeout 99 | milliseconds, 100 | .Nm 101 | will print a message to stderr and exit 99. 102 | By default, 103 | .Ar timeout 104 | is 0, which means no time limit. 105 | .El 106 | .Sh EXIT STATUS 107 | .Bl -tag -width x 108 | .It 0 109 | Success, the wanted state has been reached. 110 | .It 1 111 | The service was supposed to go up, but reported permanent failure. 112 | .It 99 113 | Timed out. 114 | .It 100 115 | Wrong usage. 116 | .It 102 117 | The 118 | .Xr s6-supervise 8 119 | process monitoring the service died. 120 | .It 111 121 | System call failed 122 | .El 123 | .Sh SEE ALSO 124 | .Xr s6-notifyoncheck 8 , 125 | .Xr s6-permafailon 8 , 126 | .Xr s6-supervise 8 , 127 | .Xr s6-svc 8 , 128 | .Xr s6-svdt 8 , 129 | .Xr s6-svdt-clear 8 , 130 | .Xr s6-svlisten 8 , 131 | .Xr s6-svok 8 , 132 | .Xr s6-svscan 8 , 133 | .Xr s6-svscanctl 8 , 134 | .Xr s6-svstat 8 , 135 | .Xr s6-svwait 8 136 | .Pp 137 | [1] 138 | .Lk https://skarnet.org/software/execline/ 139 | .Pp 140 | This man page is ported from the authoritative documentation at: 141 | .Lk https://skarnet.org/software/s6/s6-svlisten1.html 142 | .Sh AUTHORS 143 | .An Laurent Bercot 144 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 145 | -------------------------------------------------------------------------------- /man8/s6-svok.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVOK 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svok 6 | .Nd check whether an 7 | .Xr s6-service-directory 7 8 | is currently supervised 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Ar servicedir 12 | .Sh DESCRIPTION 13 | .Nm 14 | checks whether an 15 | .Xr s6-supervise 8 16 | process is currently monitoring 17 | .Ar servicedir . 18 | It exits 0 if there is one, or 1 if there is none. 19 | .Sh SEE ALSO 20 | .Xr s6-notifyoncheck 8 , 21 | .Xr s6-permafailon 8 , 22 | .Xr s6-supervise 8 , 23 | .Xr s6-svc 8 , 24 | .Xr s6-svdt 8 , 25 | .Xr s6-svdt-clear 8 , 26 | .Xr s6-svlisten 8 , 27 | .Xr s6-svlisten1 8 , 28 | .Xr s6-svscan 8 , 29 | .Xr s6-svscanctl 8 , 30 | .Xr s6-svstat 8 , 31 | .Xr s6-svwait 8 32 | .Pp 33 | This man page is ported from the authoritative documentation at: 34 | .Lk https://skarnet.org/software/s6/s6-svok.html 35 | .Sh AUTHORS 36 | .An Laurent Bercot 37 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 38 | -------------------------------------------------------------------------------- /man8/s6-svperms.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVPERMS 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svperms 6 | .Nd allows the user to see, or modify, for a given 7 | list of services: who can read their states, who can send them control 8 | commands, and who can subscribe to up/down events for those services 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl v 12 | .Op Fl u | Fl g Ar group | Fl G Ar group | Fl o | Fl O Ar group 13 | .Op Fl e | Fl E Ar group 14 | .Ar servicedirs... 15 | .Sh DESCRIPTION 16 | Without options, or with only the 17 | Fl v 18 | option, 19 | .Nm 20 | prints 3 lines to stdout for every service directory listed in 21 | .Ar servicedirs . 22 | Every line contains the name of the service directory, then the 23 | following information: 24 | .Bl -tag -width x 25 | .It status: 26 | Indicates who is allowed to read status information on the service, 27 | with commands such as 28 | .Xr s6-svstat 8 29 | or 30 | .Xr s6-svdt 8 . 31 | The values can be 32 | .Ql owner , 33 | for only the owner of the service; 34 | .Ql group: Ns Ar name , 35 | for the owner and members of group 36 | .Ar name ; 37 | or 38 | .Ql public , 39 | for all users. 40 | .It control: 41 | Indicates who is allowed to send control commands to the service, with 42 | commands such as 43 | .Xr s6-svc 8 . 44 | The values can be 45 | .Ql owner , 46 | for only the owner of the service; or 47 | .Ql group: Ns Ar name , 48 | for the owner and members of group 49 | .Ar name . 50 | .It events: 51 | Indicates who is allowed to subscribed to events sent by 52 | .Xr s6-supervise 8 53 | for this service, with commands such as 54 | .Xr s6-svwait 8 55 | or 56 | .Xr s6-svlisten1 8 . 57 | The values can be 58 | .Ql group: Ns Ar name , 59 | for the owner and members of group 60 | .Ar name ; 61 | or 62 | .Ql public , 63 | for all users. 64 | .El 65 | .Pp 66 | If something goes wrong while reading a part of the configuration of a 67 | service directory, 68 | .Nm 69 | does not print the corresponding line to stdout; instead, it prints a 70 | warning message to stderr. 71 | .Pp 72 | When invoked with other options, 73 | .Nm 74 | modifies the permissions of the service directories listed in 75 | .Ar servicedirs... 76 | as specified by the options. 77 | The same permissions will be applied to all the services listed in 78 | .Ar servicedirs... . 79 | .Pp 80 | The default (restrictive) permissions are safe. 81 | .Pp 82 | Unless operation of a service is restricted information, it is also 83 | safe to make 84 | .Ql status\&: 85 | more permissive. 86 | .Pp 87 | Opening 88 | .Ql control\&: 89 | to a group can be useful for instance in a shared administration 90 | situation when individual administrators are not given full root 91 | powers. 92 | .Pp 93 | Making 94 | .Ql events\&: 95 | public bears a small risk of a local DoS attack preventing more 96 | subscriptions to events, so it is not recommended for supervision 97 | trees where such subscriptions are critical to operations - such as a 98 | set of root services managed by s6-rc[1]. 99 | .Sh OPTIONS 100 | .Bl -tag -width x 101 | .It Fl v 102 | Re-read the permissions after writing them, and print them to stdout. 103 | .It Fl u 104 | Restrict the 105 | .Ql status\&: 106 | and 107 | .Ql control\&: 108 | permissions to 109 | .Ql owner : 110 | only the owner of a service directory will be able to read its state 111 | or control the service. 112 | This is the default when 113 | .Xr s6-supervise 8 114 | starts a service for the first time. 115 | .It Fl g Ar group 116 | Allow members of group 117 | .Ar group 118 | to read the status of the service, but not to control it - control 119 | will be restricted to the owner. 120 | .It Fl G Ar group 121 | Allow members of group 122 | .Ar group 123 | to read 124 | .Em and 125 | control the service. 126 | .It Fl o 127 | Allow everyone to read the status of the service, but restrict 128 | .Ql control\&: 129 | to the owner. 130 | .It Fl O Ar group 131 | Allow everyone to read the status, and allow members of group 132 | .Ar group 133 | to control the service. 134 | .It Fl e 135 | Allow everyone to subscribe to events. 136 | .It Fl E Ar group 137 | Only allow members of group 138 | .Ar group 139 | to subscribe to events. 140 | This is the default when 141 | .Xr s6-supervise 8 142 | starts a service for the first time, with 143 | .Ar group 144 | being the primary group of the 145 | .Xr s6-supervise 8 146 | process 147 | .Po 148 | most likely 149 | .Ql root 150 | .Pc . 151 | .El 152 | .Pp 153 | .Ar group 154 | is normally a group name that will be searched in the group 155 | database. 156 | But if it starts with a colon 157 | .Po 158 | .Ql \&: 159 | .Pc , 160 | the rest of 161 | .Ar group 162 | will be interpreted as a numerical gid, and the group database will 163 | not be read. 164 | .Sh EXIT STATUS 165 | .Bl -tag -width x 166 | .It 0 167 | Success. 168 | .It 1 169 | Something went wrong when reading permissions in one of the service directories. 170 | .It 100 171 | Wrong usage. 172 | .It 111 173 | System call failed. 174 | .El 175 | .Sh SEE ALSO 176 | [1] 177 | .Lk https://skarnet.org/software/s6-rc/ 178 | .Pp 179 | This man page is ported from the authoritative documentation at: 180 | .Lk https://skarnet.org/software/s6/s6-svperms.html 181 | .Sh AUTHORS 182 | .An Laurent Bercot 183 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 184 | -------------------------------------------------------------------------------- /man8/s6-svscanctl.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVSCANCTL 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svscanctl 6 | .Nd send commands to a running 7 | .Xr s6-svscan 8 8 | process 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl zabhitqnN 12 | .Ar scandir 13 | .Sh DESCRIPTION 14 | .Nm 15 | sends the given series of commands to the 16 | .Xr s6-svscan 8 17 | process monitoring the 18 | .Ar scandir 19 | directory, then exits 0. 20 | It exits 111 if it cannot send a command, or 21 | 100 if no 22 | .Xr s6-svscan 8 23 | process is running on 24 | .Ar scandir . 25 | .Sh OPTIONS 26 | .Bl -tag -width x 27 | .It Fl a 28 | Alarm. 29 | .Xr s6-svscan 8 30 | will immediately perform a scan of 31 | .Ar scandir 32 | to check for services. 33 | .It Fl z 34 | Destroy zombies. 35 | Immediately triggers 36 | .Xr s6-svscan 8 Ap 37 | s reaper mechanism. 38 | .It Fl b 39 | Abort. 40 | .Xr s6-svscan 8 41 | will exec into its finishing procedure. 42 | It will not kill any of the maintained 43 | .Xr s6-supervise 8 44 | processes, unless a 45 | .Fl t 46 | or 47 | .Fl q 48 | option is also present before the 49 | .Fl b 50 | option in the 51 | .Nm 52 | invocation. 53 | .It Fl h 54 | Reload configuration. 55 | .Xr s6-svscan 8 56 | will perform a scan, and destroy inactive services. 57 | Equivalent to 58 | .Fl an . 59 | .Fl i 60 | Equivalent to 61 | .Fl t 62 | below. 63 | .It Fl t 64 | Terminate. 65 | .Xr s6-svscan 8 66 | will send a 67 | .Dv SIGTERM 68 | to all the 69 | .Xr s6-supervise 8 70 | processes supervising a service and a 71 | .Dv SIGHUP 72 | to all the 73 | .Xr s6-supervise 8 74 | processes supervising a logger, then exec into its finish 75 | procedure. 76 | This means that services will be brought down but loggers will exit 77 | naturally on EOF, and 78 | .Xr s6-svscan 8 79 | will wait for them to exit before exec'ing into 80 | .Pa .s6-svscan/finish 81 | or exiting itself: it's a clean shutdown with no loss of logs. 82 | .It Fl q 83 | Quit. 84 | .Xr s6-svscan 8 85 | will send all its 86 | .Xr s6-supervise 8 87 | processes a 88 | .Dv SIGTERM , 89 | then exec into its finish procedure. 90 | This is different from 91 | .Fl t 92 | in that services 93 | .Em and 94 | loggers will be forcibly killed, so the quit procedure may be faster 95 | but in-flight logs may be lost. 96 | .It Fl n 97 | Nuke. 98 | .Xr s6-svscan 8 99 | will kill all the 100 | .Xr s6-supervise 8 101 | processes it has launched but that did not match a service directory 102 | last time 103 | .Ar scandir 104 | was scanned, i.e. it prunes the supervision tree so that it matches 105 | exactly what was in 106 | .Ar scandir 107 | at the time of the last scan. 108 | A SIGTERM is sent to the 109 | .Xr s6-supervise 8 110 | processes supervising services and a SIGHUP is sent to the 111 | .Xr s6-supervise 8 112 | processes supervising loggers. 113 | .It Fl N 114 | Really nuke. 115 | Does the same thing as 116 | .Fl n , 117 | except that SIGTERM is sent to all the relevant 118 | .Xr s6-supervise 8 119 | processes, even if they are supervising loggers. 120 | This is not recommended in a situation where you do not need to tear 121 | down the supervision tree. 122 | .El 123 | .Sh IMPLEMENTATION NOTES 124 | .Nm 125 | writes control commands into the 126 | .Pa scandir/.s6-svscan/control 127 | FIFO. 128 | An 129 | .Xr s6-svscan 8 130 | process running on 131 | .Ar scandir 132 | will be listening to this FIFO, and will read and interpret those 133 | commands. 134 | .Sh SEE ALSO 135 | .Xr s6-notifyoncheck 8 , 136 | .Xr s6-permafailon 8 , 137 | .Xr s6-supervise 8 , 138 | .Xr s6-svc 8 , 139 | .Xr s6-svdt 8 , 140 | .Xr s6-svdt-clear 8 , 141 | .Xr s6-svlisten 8 , 142 | .Xr s6-svlisten1 8 , 143 | .Xr s6-svok 8 , 144 | .Xr s6-svscan 8 , 145 | .Xr s6-svstat 8 , 146 | .Xr s6-svwait 8 147 | .Pp 148 | This man page is ported from the authoritative documentation at: 149 | .Lk https://skarnet.org/software/s6/s6-svscanctl.html 150 | .Sh AUTHORS 151 | .An Laurent Bercot 152 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 153 | -------------------------------------------------------------------------------- /man8/s6-svunlink.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVUNLINK 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svunlink 6 | .Nd integrate service directories into an existing service manager sequence and eliminate race conditions 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl X 10 | .Op Fl t Ar timeout 11 | .Ar scandir 12 | .Ar name 13 | .Sh DESCRIPTION 14 | .Nm 15 | unlinks an 16 | .Xr s6-service-directory 7 17 | from an 18 | .Xr s6-scan-directory 7 , 19 | then notifies 20 | .Xr s6-svscan 8 21 | that a service has been unregistered. 22 | It waits until the 23 | .Xr s6-supervise 8 24 | supervisor process managing the service has disappeared, then exits. 25 | .Bl -bullet -width x 26 | .It 27 | .Nm 28 | expects a running 29 | .Xr s6-svscan 8 30 | process on 31 | .Ar scandir 32 | and a fully functional supervised service on the 33 | .Xr s6-service-directory 7 34 | in 35 | .Ql Ar scandir Ns / Ns Ar name , 36 | which must be a symbolic link to a real directory located somewhere 37 | else. 38 | .It 39 | It deletes the 40 | .Ql Ar scandir Ns / Ns Ar name 41 | symlink. 42 | .It 43 | It sends a command to 44 | .Xr s6-svscan 8 45 | to signal it that a service has disappeared. 46 | .It 47 | It waits for the 48 | .Xr s6-supervise 8 49 | process managing the service directory to exit. 50 | .It 51 | It exits 0. 52 | .El 53 | .Pp 54 | Using 55 | .Nm 56 | to stop services is a suboptimal pattern: starting and stopping 57 | supervisors is a heavier operation than just stopping services. 58 | The simpler, more efficient pattern is to simply perform 59 | .Ql s6-svc -dwD Ar scandir Ns / Ns Ar name , 60 | which only commands, and waits for, the death of the service, without 61 | impacting the supervisor. 62 | Nevertheless, for symmetry with 63 | .Xr s6-svlink 8 , 64 | this program is provided. 65 | .Pp 66 | .Nm 67 | is a destructor; as is, it returns 0 even in situations that are 68 | nominal failures. 69 | For instance, it returns 0 even if its timeout expires; the rationale 70 | is that there is no sensible action for the user to do if this error 71 | is reported. 72 | .Nm 73 | only reports errors when they uncover a deeper problem in the system. 74 | .Pp 75 | .Nm 76 | sends a 77 | .Ql s6-svscanctl -an 78 | command to 79 | .Ar scandir , 80 | which means that the system's view of services will be refreshed and 81 | inactive services will be killed and unsupervised. 82 | Depending on what links exist in 83 | .Ar scandir , 84 | new services may appear, and other services than 85 | .Ar name 86 | may disappear. 87 | .Sh OPTIONS 88 | .Bl -tag -width x 89 | .It Fl X 90 | Don't wait. 91 | .Nm 92 | will exit right away, without waiting for the supervisor to exit first. 93 | .It Fl t Ar timeout 94 | If the supervisor has not exited after 95 | .Ar timeout 96 | milliseconds, 97 | .Nm 98 | will still exit. 99 | The default is 0, meaning no time limit. 100 | .El 101 | .Sh EXIT STATUS 102 | .Bl -tag -width x 103 | .It 0 104 | Success. 105 | .It 100 106 | Wrong usage. 107 | .It 111 108 | System call failed. 109 | .El 110 | .Sh SEE ALSO 111 | .Xr s6-scan-directory 7 , 112 | .Xr s6-service-directory 7 , 113 | .Xr s6-supervise 8 , 114 | .Xr s6-svlink 8 , 115 | .Xr s6-svscan 8 116 | .Pp 117 | This man page is ported from the authoritative documentation at: 118 | .Lk https://skarnet.org/software/s6/s6-svunlink.html 119 | .Sh AUTHORS 120 | .An Laurent Bercot 121 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 122 | -------------------------------------------------------------------------------- /man8/s6-svwait.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-SVWAIT 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-svwait 6 | .Nd monitor one or more 7 | .Xr s6-service-directory 7 Ns s 8 | given as its arguments, waiting for a state (ready, up or down) to 9 | happen 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl U | u | D | d | r | R 13 | .Op Fl a | o 14 | .Op Fl t Ar timeout 15 | .Ar servicedir... 16 | .Sh DESCRIPTION 17 | .Nm 18 | only waits for notifications; it never polls. 19 | .Pp 20 | .Nm 21 | should be given one or more 22 | .Em service directories 23 | as arguments, not an 24 | .Xr s6-scan-directory 7 . 25 | If you need to wait for a whole scan directory, give all its contents 26 | as arguments to 27 | .Nm s6-svwait . 28 | .Pp 29 | .Nm 30 | will only work on service directories that are already active, 31 | i.e. have an 32 | .Xr s6-supervise 8 33 | process running on them. 34 | It will not work on a service directory where 35 | .Xr s6-supervise 8 36 | has not been started yet. 37 | .Sh OPTIONS 38 | .Bl -tag -width x 39 | .It Fl u 40 | Up. 41 | .Nm 42 | will wait until the services are up, as reported by 43 | .Xr s6-supervise 8 . 44 | This is the default; it is not reliable, but it does not depend on 45 | specific support in the service programs. 46 | See 47 | .Xr s6-notifywhenup 7 48 | for details. 49 | .It Fl U 50 | Really up. 51 | .Nm 52 | will wait until the services are up and ready as reported by the 53 | services themselves. 54 | This requires specific support in the service programs, and the use of 55 | the 56 | .Pa notification-fd 57 | file in the 58 | .Xr s6-service-directory 7 . 59 | See the explanation in 60 | .Xr s6-notifywhenup 7 . 61 | .It Fl d 62 | Down. 63 | .Nm 64 | will wait until the services are down. 65 | .It Fl D 66 | Really down. 67 | .Nm 68 | will wait until the services are down and the cleanup scripts in 69 | .Sm off 70 | .Ar servicedir / 71 | .Pa finish 72 | .Sm on 73 | for every 74 | .Ar servicedir 75 | have finished executing (or have timed out and been killed). 76 | .It Fl r 77 | Restart. 78 | .Nm 79 | will wait until the services are down, then until they are up. 80 | If the 81 | .Fl o 82 | option is given, it waits until 83 | .Em all 84 | services are down and 85 | .Em one 86 | service is up; otherwise it waits until 87 | .Em all 88 | the services have restarted. 89 | .It Fl R 90 | Restart and ready. 91 | .Nm 92 | will wait until the services are down, then until they are up and 93 | ready. 94 | If the 95 | .Fl o 96 | option is given, it waits until 97 | .Em all 98 | services are down and 99 | .Em one 100 | service is up and ready; otherwise it waits until 101 | .Em all 102 | the services have restarted and are ready. 103 | .It Fl o 104 | Or. 105 | .Nm 106 | will wait until 107 | .Em one 108 | of the given services comes up or down. 109 | .It Fl a 110 | And. 111 | .Nm 112 | will wait until 113 | .Em all 114 | of the given services come up or down. 115 | This is the default. 116 | .It Fl t Ar timeout 117 | If the requested events have not happened after timeout milliseconds, 118 | .Nm 119 | will print a message to stderr and exit 99. 120 | By default, 121 | .Ar timeout 122 | is 0, which means no time limit. 123 | .El 124 | .Sh IMPLEMENTATION NOTES 125 | .Nm 126 | spawns an 127 | .Xr s6-ftrigrd 8 128 | child to listen to notifications sent by 129 | .Xr s6-supervise 8 . 130 | It also checks 131 | .Pa supervise/status 132 | files to get the current service states, so it is immune to race 133 | conditions. 134 | .Sh EXIT STATUS 135 | .Bl -tag -width x 136 | .It 0 137 | Success, the wanted state has been reached. 138 | .It 99 139 | Timed out. 140 | .It 100 141 | Wrong usage. 142 | .It 102 143 | The 144 | .Xr s6-supervise 8 145 | process monitoring the service died. 146 | .It 111 147 | System call failed. 148 | .It Em n 149 | Services were expected to come up, but 150 | .Em n 151 | of them reported permanent failure. 152 | .El 153 | .Sh SEE ALSO 154 | .Xr s6-notifyoncheck 8 , 155 | .Xr s6-permafailon 8 , 156 | .Xr s6-supervise 8 , 157 | .Xr s6-svc 8 , 158 | .Xr s6-svdt 8 , 159 | .Xr s6-svdt-clear 8 , 160 | .Xr s6-svlisten 8 , 161 | .Xr s6-svlisten1 8 , 162 | .Xr s6-svok 8 , 163 | .Xr s6-svscan 8 , 164 | .Xr s6-svscanctl 8 , 165 | .Xr s6-svstat 8 166 | .Pp 167 | This man page is ported from the authoritative documentation at: 168 | .Lk https://skarnet.org/software/s6/s6-svwait.html 169 | .Sh AUTHORS 170 | .An Laurent Bercot 171 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 172 | -------------------------------------------------------------------------------- /man8/s6-tai64n.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-TAI64N 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-tai64n 6 | .Nd read from stdin and write to stdout, prepending lines with a TAI64N timestamp[1] and a space 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Sh DESCRIPTION 10 | .Nm 11 | exits 0 when it sees the end of stdin. 12 | If there's an unfinished line, 13 | .Nm 14 | processes it, adds a newline character to it, and writes it before 15 | exiting. 16 | .Pp 17 | .Nm 18 | does neither 19 | .Dq line buffering 20 | nor 21 | .Dq block buffering . 22 | It does optimal buffering, i.e. it flushes its output buffer every 23 | time it risks blocking on input. 24 | Every filter should behave this way, whether its output is a tty or 25 | not: it's simpler and more efficient in every case. 26 | .Sh SEE ALSO 27 | .Xr s6-applyuidgid 8 , 28 | .Xr s6-envdir 8 , 29 | .Xr s6-envuidgid 8 , 30 | .Xr s6-fghack 8 , 31 | .Xr s6-setsid 8 , 32 | .Xr s6-setuidgid 8 , 33 | .Xr s6-softlimit 8 , 34 | .Xr s6-tai64nlocal 8 35 | .Pp 36 | [1] 37 | .Lk https://skarnet.org/software/skalibs/libstddjb/tai.html#timestamp 38 | .Pp 39 | This man page is ported from the authoritative documentation at: 40 | .Lk https://skarnet.org/software/s6/s6-tai64n.html 41 | .Sh AUTHORS 42 | .An Laurent Bercot 43 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 44 | -------------------------------------------------------------------------------- /man8/s6-tai64nlocal.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6-TAI64NLOCAL 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6-tai64nlocal 6 | .Nd read from stdin and write to stdout, replacing every line beginning with a TAI64N timestamp[1] with a human-readable local date and time 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl g 10 | .Sh DESCRIPTION 11 | .Nm 12 | exits 0 when it sees the end of stdin. 13 | If there's an unfinished line, 14 | .Nm 15 | processes it and writes it before exiting. 16 | .Pp 17 | The typical use case of 18 | .Nm 19 | is to read files that have been filtered through 20 | .Xr s6-tai64n 8 , 21 | or log files that have been produced by 22 | .Xr s6-log 8 23 | with the 24 | .Fl t 25 | option. 26 | For instance, to read the latest httpd logs with human-readable 27 | timestamps, 28 | .Ql s6-tai64nlocal < /var/log/httpd/current | less 29 | is a possible command. 30 | .Pp 31 | .Nm 32 | does neither 33 | .Dq line buffering 34 | nor 35 | .Dq block buffering . 36 | It does optimal buffering, i.e. it flushes its output buffer every 37 | time it risks blocking on input. 38 | .Pp 39 | If 40 | .Nm 41 | does not appear to give the correct local time: 42 | .Bl -bullet -width x 43 | .It 44 | Check the compilation options that were used for the skalibs[2] libraries 45 | your 46 | .Nm s6-tai64nlocal 47 | program was linked against. 48 | In particular, check whether the 49 | .Ql --enable-tai-clock 50 | or 51 | .Ql --enable-right-tz 52 | configure options have been given. 53 | .It 54 | Compare these flags and their meanings with your current timezone. 55 | In particular, check 56 | .Pa /etc/localtime , 57 | .Pa /etc/timezone , 58 | .Pa /etc/TZ , 59 | and the 60 | .Ev TZ 61 | environment variable. 62 | .El 63 | .Sh OPTIONS 64 | .Bl -tag -width x 65 | .It Fl g 66 | Print GMT time instead of local time. 67 | .El 68 | .Sh SEE ALSO 69 | .Xr s6-applyuidgid 8 , 70 | .Xr s6-envdir 8 , 71 | .Xr s6-envuidgid 8 , 72 | .Xr s6-fghack 8 , 73 | .Xr s6-setsid 8 , 74 | .Xr s6-setuidgid 8 , 75 | .Xr s6-softlimit 8 , 76 | .Xr s6-tai64n 8 77 | .Pp 78 | [1] 79 | .Lk https://skarnet.org/software/skalibs/libstddjb/tai.html#timestamp 80 | .Pp 81 | [2] 82 | .Lk https://skarnet.org/software/skalibs/ 83 | .Pp 84 | This man page is ported from the authoritative documentation at: 85 | .Lk https://skarnet.org/software/s6/s6-tai64nlocal.html 86 | .Sh AUTHORS 87 | .An Laurent Bercot 88 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 89 | -------------------------------------------------------------------------------- /man8/s6lockd-helper.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6LOCKD-HELPER 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6lockd-helper 6 | .Nd helper program for the 7 | .Xr s6lockd 8 8 | daemon 9 | .Sh DESCRIPTION 10 | .Nm 11 | just acquires a lock and holds it until it is killed or told to exit 12 | by its parent daemon. 13 | .Nm 14 | is not meant to be invoked directly by the user: it will be spawned by 15 | the 16 | .Xr s6lockd 8 17 | program. 18 | .Pp 19 | .Nm 20 | blocks on lock acquisition until it succeeds. 21 | It then notifies its parent. 22 | It exits when its parent tells it to (i.e. when the client asks for 23 | lock release). 24 | During the lock acquisition phase, it can be killed if its parent 25 | detects a timeout. 26 | .Pp 27 | One 28 | .Nm 29 | process per lock is the only way (apart from threads) to implement 30 | timed lock acquisition. 31 | This can lead to a lot of 32 | .Nm 33 | processes, but this is not a problem: 34 | .Bl -bullet -width x 35 | .It 36 | Processes are not a scarce resource. 37 | Today's schedulers work in O(1), or in O(a function of the number of 38 | runnable processes), which means that a sleeping process takes no 39 | scheduling time at all. 40 | .It 41 | .Nm 42 | is extremely tiny. 43 | Every instance should use up at most one or two pages of non-sharable 44 | memory. 45 | .El 46 | .Sh SEE ALSO 47 | .Xr s6-setlock 8 , 48 | .Xr s6lockd 8 49 | .Pp 50 | This man page is ported from the authoritative documentation at: 51 | .Lk https://skarnet.org/software/s6/libs6/s6lockd-helper.html 52 | .Sh AUTHORS 53 | .An Laurent Bercot 54 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 55 | -------------------------------------------------------------------------------- /man8/s6lockd.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt S6LOCKD 8 3 | .Os 4 | .Sh NAME 5 | .Nm s6lockd 6 | .Nd 7 | .Xr s6-s6lock 7 8 | daemon which manages a set of lock files in a given directory, and 9 | associated timeouts 10 | .Sh DESCRIPTION 11 | .Nm 12 | does not fork, does not background itself automatically, and does not 13 | use syslog. 14 | It is not meant to be run directly by the user: it will be spawned by 15 | the 16 | .Xr s6-s6lock 7 17 | client library. 18 | .Pp 19 | There are two ways to use 20 | .Nm : 21 | .Bl -enum -width x 22 | .It 23 | Use the 24 | .Fn s6lock_startf 25 | library call. 26 | An 27 | .Nm 28 | child will then be spawned from your calling process, and 29 | automatically reaped when you call 30 | .Fn s6lock_end . 31 | It requires care with applications that trap SIGCHLD. 32 | It also requires care with lock file permissions: an 33 | .Nm 34 | instance might not be able to open a lock file created by a former 35 | instance run by another client with different permissions. 36 | .It 37 | Use the 38 | .Fn s6lock_start 39 | library call, together with an 40 | .Nm 41 | .Xr s6-local-service 7 . 42 | For once, 43 | .Em this is the recommended setup : 44 | .Nm 45 | creates empty lock files, and having all 46 | .Nm 47 | instances run under the same user simplifies permissions management 48 | considerably. 49 | .El 50 | .Pp 51 | When run as a service, 52 | .Nm 53 | has no 54 | .Dq standalone 55 | mode: it is designed to work with a Unix domain super-server, like 56 | .Xr s6-ipcserver 8 . 57 | .Nm 58 | follows the UCSPI[1] interface; it can be directly executed from the 59 | super-server. 60 | .Pp 61 | Unix does not natively provide a way to stop blocking on a lock 62 | acquisition after a timeout. 63 | To emulate such behaviour, 64 | .Nm 65 | actually spawns an 66 | .Xr s6lockd-helper 8 67 | child per requested lock. 68 | .Sh SEE ALSO 69 | .Xr s6-setlock 8 , 70 | .Xr s6lockd-helper 8 71 | .Pp 72 | [1] 73 | .Lk https://cr.yp.to/proto/ucspi.txt 74 | .Pp 75 | This man page is ported from the authoritative documentation at: 76 | .Lk https://skarnet.org/software/s6/libs6/s6lockd.html 77 | .Sh AUTHORS 78 | .An Laurent Bercot 79 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 80 | -------------------------------------------------------------------------------- /man8/ucspilogd.8: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt UCSPILOGD 8 3 | .Os 4 | .Sh NAME 5 | .Nm ucspilogd 6 | .Nd convert syslog facility numbers and alert levels into names 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl d Ar undef 10 | .Op Ar var ... 11 | .Sh DESCRIPTION 12 | .Nm 13 | reads a stream of syslog-like messages on stdin. 14 | Those messages can be newline-terminated or null-terminated. 15 | .Pp 16 | For every line it reads: if it has been given 17 | .Ar var 18 | arguments, it writes the value of every 19 | .Ar var 20 | environment variable, followed by a colon and a space. 21 | .Pp 22 | If the line begins with a syslog facility number and/or alert level in 23 | the syslog format, it converts them into a human-readable name in the 24 | syslogd fashion. 25 | .Pp 26 | It then writes the processed line to stdout. 27 | .Pp 28 | You can emulate the whole syslogd behaviour by combining the following 29 | components: 30 | .Bl -bullet -width x 31 | .It 32 | A Unix stream super-server such as 33 | .Xr s6-ipcserver 8 34 | listening to the Unix domain socket 35 | .Pa /dev/log , 36 | to connect to the kernel log-reading interface. 37 | .It 38 | .Nm 39 | running under that super-server, to read the logs and perform adequate 40 | transformations. 41 | .It 42 | A logger such as 43 | .Xr s6-log 8 44 | to store the logs into the filesystem. 45 | .It 46 | A supervision mechanism such as s6, to ensure ease of use and 47 | reliability of the whole chain. 48 | .El 49 | .Pp 50 | The resulting suite of programs is still smaller, and way more 51 | reliable, than a standard syslogd. 52 | .Pp 53 | In the 54 | .Pa examples/syslogd-linux 55 | subdirectory of the s6 package, you will find a suitable ucspilogd 56 | .Xr s6-service-directory 7 . 57 | The run scripts are written in the execline[1] language. 58 | .Pp 59 | .Sy Using ucspilogd as a klogd replacement 60 | .Pp 61 | Certain Unix kernels offer a nice interface to the kernel logs. 62 | For instance, the Linux kernel provides the 63 | .Pa /proc/kmsg 64 | fake file, that can be opened and read like a normal file, excepts 65 | that it gives the kernel logs when they are available and blocks 66 | otherwise. 67 | You can use 68 | .Nm 69 | to process data from those interfaces. 70 | .Pp 71 | The 72 | .Pa examples/klogd-linux 73 | subdirectory of the s6 package is an 74 | .Xr s6-service-directory 7 75 | providing such a klogd service for Linux, using the 76 | .Pa /proc/kmsg 77 | interface. 78 | .Sh OPTIONS 79 | .Bl -tag -width x 80 | .It Fl d Ar undef 81 | When a variable 82 | .Ar var 83 | given on the command line is actually undefined at 84 | .Nm 85 | execution time, print 86 | .Ar undef 87 | in place of what would be the variable's value on every line. 88 | Default is the string 89 | .Ql . 90 | .El 91 | .Sh SEE ALSO 92 | .Xr s6-log 8 93 | .Pp 94 | [1] 95 | .Lk https://skarnet.org/software/execline/ 96 | .Pp 97 | This man page is ported from the authoritative documentation at: 98 | .Lk https://skarnet.org/software/s6/ucspilogd.html 99 | .Sh AUTHORS 100 | .An Laurent Bercot 101 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 102 | --------------------------------------------------------------------------------