s6: the s6-fdholder-transferdump program
Keywords: s6 s6-fdholder fd-holding fd-holder fd dump transfer unix socket activation

s6
Software
skarnet.org

# The `s6-fdholder-transferdump` program

`s6-fdholder-transferdump` connects to two separate fd-holding daemons and transfers the content of the first one to the second one.

## Interface

         s6-fdholder-transferdump [ -t timeoutfrom:timeoutto ] pathfrom pathto

- `s6-fdholder-transferdump` connects to a s6-fdholderd server process listening on pathfrom and gets the whole set of file descriptors from this server, with their identifiers and (when relevant) expiration dates.
- It then connects to a different instance of s6-fdholderd, listening on pathto, and stores the set of file descriptors to it. The set is added to the second server, which keeps the descriptors it was already holding.

## Options

- `-t timeoutfrom:timeoutto` : if the operations cannot be processed in timeoutfrom (for the connection to pathfrom) or timeoutto (for the connection to pathto) milliseconds, then fail with an error message. Communications with the servers should be near-instant, so this option is only here to protect users against programming errors (connecting to the wrong socket, for instance).

## Exit codes

- 0: success.
- 1: the source server denied the operation. The meaning of the error messages is explained here.
- 2: the destination server denied the operation. The meaning of the error messages is explained here.
- 100: wrong usage.
- 111: system call failed - this includes attempting to connect to a nonexistent socket, or one where no s6-fdholderd daemon is listening.

## Notes

- Dumping the entire state of s6-fdholderd requires special authorizations. Make sure the s6-fdholderd instances are configured to accept dump-getting and dump-setting requests from your client.
- A typical use case of s6-fdholder-transferdump is when the main fd-holding daemon needs to upgrade, or restart for some reason. Transferring the file descriptors into another, temporary fd-holding daemon instance allows it to restart without losing the descriptors.