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. ["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.

Disabling the Shell Startup File

If your remote shell is C shell or tcsh, it normally reads your remote shell startup file (cshrc, tcshrc) at the beginning of the session. Some commands in these startup files, particularly those that write to standard output, may interfere with the file-copy commands scp2 and sftp. In SSH2, file copying is accomplished by the sftp-server subsystem, so SSH2 disables reading of cshrc and tcshrc for subsystems. ["SSH-1 backward compatibility"] You can reenable this with the keyword AllowCshrc-SourcingWithSubsystems, providing a value of yes (permit cshrc and tcshrc sourcing) or no (the default): 

# SSH2 only AllowCshrcSourcingWithSubsystems yes


SSH2 disables the sourcing of remote cshrc and tcshrc files by passing the -f command-line option to the remote C shell or tcsh invocation.