altsign-agent(8)

ALTSIGN-AGENT(8)

System Administration

ALTSIGN-AGENT(8)

NAME

altsign-agent - control daemon for altsign signing sessions

SYNOPSIS

altsign-agent [OPTIONS]

DESCRIPTION

altsign-agent is a local control daemon that brokers signing sessions for the altsign service. It listens on a control UNIX domain socket and accepts requests to start a signing session for a specific certificate nickname. Authorized clients receive a session socket path, which they can use to submit signing requests.

Each session is served by a forked child that listens on the session socket and invokes ssh(1) to execute a remote signing command:

: ssh SERVER sign {module|PE} CERT

The daemon refuses to run as root. The control socket directory must already exist. The session socket directory must also already exist.

OPTIONS

-S, --socket=SOCKET: Control socket path (default: /run/altsign-module/control.sock). If not specified, the default is selected by the mode flags (--module by default, --pe for PE). You can also set ALTSIGN_AGENT_SOCKET.
-T, --session-socket=SOCKET: Session socket path (default: /run/altsign-module/session/sockdir/session.sock). If not specified, the default is selected by the mode flags (--module by default, --pe for PE). You can also set ALTSIGN_AGENT_SESSION_SOCKET.
--module: Use module socket paths when selecting defaults. This is the default mode. This option is mutually exclusive with --pe.
--pe: Use PE socket paths when selecting defaults. This option is mutually exclusive with --module.
-g, --admin-group=GROUP: Administrative group allowed to open the control socket. Default: altsign-admin. You can also set ALTSIGN_AGENT_ADMIN_GROUP.
-s, --server=SERVER: SSH server name or alias used for signing. This option is required unless ALTSIGN_AGENT_SERVER is set.
-v, --verbose: Enable verbose logging. You can also set ALTSIGN_AGENT_VERBOSE to any non-empty, non-zero value.
-y, --syslog: Enable syslog logging. You can also set ALTSIGN_AGENT_SYSLOG to any non-empty, non-zero value.
-?, --help: Show the full help text.
--usage: Show a short usage summary.

ENVIRONMENT

ALTSIGN_AGENT_SOCKET: Default control socket path (overridden by --socket).
ALTSIGN_AGENT_SESSION_SOCKET: Default session socket path (overridden by --session-socket).
ALTSIGN_AGENT_ADMIN_GROUP: Default administrative group (overridden by --admin-group).
ALTSIGN_AGENT_SERVER: Default SSH server (overridden by --server).
ALTSIGN_AGENT_VERBOSE: Enable verbose logging when set to a non-empty, non-zero value.
ALTSIGN_AGENT_SYSLOG: Enable syslog logging when set to a non-empty, non-zero value.
ALTSIGN_AGENT_DRY_RUN: When set, the session daemon skips remote signing and simply copies input to output.

ACCESS CONTROL

Control socket clients are authorized by peer credentials. Root is always allowed. Non-root clients must belong to the administrative group.

FILES

/run/altsign-module/control.sock: Module service control socket.
/run/altsign-pe/control.sock: PE service control socket.
/run/altsign-module/session/sockdir: Module service session socket directory.
/run/altsign-pe/session/sockdir: PE service session socket directory.
/run/altsign-module/session/sockdir/session.sock: Module service session socket path.
/run/altsign-pe/session/sockdir/session.sock: PE service session socket path.
/usr/bin/ssh: SSH client used for remote signing.

EXIT STATUS

0: Exited cleanly.
non-zero: An error occurred during startup or runtime.

EXAMPLES

Start the agent daemon with an explicit SSH server (module mode by default):

altsign-agent --server signer.example.org

Start the agent daemon in PE mode (select PE default socket paths):

altsign-agent --pe --server signer.example.org