5.7. Subsystems

Subsystems are a (mostly undocumented) layer of abstraction for defining and invoking remote commands in SSH2 and OpenSSH/2. Normally you invoke remote commands ad hoc by providing them on the client command line. For instance, the following line invokes the Unix backup program tar remotely to copy the /home directory to tape:

# SSH2, OpenSSH/2
$ ssh server.example.com /bin/tar c /home

Subsystems are a set of remote commands predefined on the server machine so they can be executed conveniently.[73] These commands are defined in the server configuration file, and the syntax is slightly different between OpenSSH and SSH2. A subsystem for invoking the preceding backup command is:

[73]Abstractly, a subsystem need not be a separate program; it can invoke a function built into the SSH server itself (hence the name). But there are no such implementations at the moment.

# SSH2
subsystem-backups       /bin/tar c /home

# OpenSSH/2
subsystem backups       /bin/tar c /home

Note that SSH2 uses a keyword of the form "subsystem-name" with one argument, whereas OpenSSH uses the keyword "subsystem" with two arguments. This SSH2 syntax is quite odd and unlike anything else in its configuration language; we don't know how it ended up that way.

To run this command on the server machine, invoke ssh with the -s option:

# SSH2, OpenSSH/2
$ ssh -s backups server.example.com

This command behaves identically to the previous one in which /bin/tar was invoked explicitly.

The default sshd2_config file defines one subsystem:

subsystem-sftp     sftp-server

WARNING: Don't remove the subsystem-sftp line from sshd2_config: it is required for scp2 and sftp to work. Internally, both programs run ssh2 -s sftp to perform file transfers.

Subsystems are mainly a convenience feature to predefine commands for SSH clients to invoke easily. The additional level of abstraction can be helpful to system administrators, who can define and advertise useful subsystems for their users. Suppose your users run the Pine email reader to connect to your IMAP server using SSH2 to secure the connection. [Section 11.3, "Pine, IMAP, and SSH"] Instead of telling everyone to use the command:

$ ssh2 server.example.com /usr/sbin/imapd

and revealing the path to the IMAP daemon, imapd, you can define a subsystem to hide the path in case it changes in the future:

# SSH2 only
subsystem-imap		 /usr/sbin/imapd

Now users can run the command:

$ ssh2 -s imap server.example.com

to establish secure IMAP connections via the subsystem.

---