NervesSSH

Manage an SSH daemon and its subsystems on Nerves devices

Usage

This library wraps Erlang/OTP's SSH daemon to make it easier to use reliably with Nerves devices.

Most importantly, it makes it possible to segment failures in other OTP applications from terminating the daemon and it recovers from rare scenarios where the daemon terminates without automatically restarting.

If you're using :nerves_pack v0.4.0 or later, you don't need to do anything except, perhaps, modify the :nerves_ssh's configuration in your config.exs. If you are not using :nerves_pack, add :nerves_ssh to your mix dependency list:

def deps do
  [
    {:nerves_ssh, "~> 0.1.0", targets: @all_targets}
  ]
end

And then include it in :shoehorn's :init list:

config :shoehorn,
  init: [:nerves_runtime, :vintage_net, :nerves_ssh]

:nerves_ssh will work if you do not add it to the :init list. However, if your main OTP application stops, OTP may stop :nerves_ssh, and that would make your device inaccessible via SSH.

Configuration

NervesSSH supports a few pieces of configuration via the application config:

• :authorized_keys - a list of SSH authorized key file string
• :user_passwords - a list of username/password tuples (stored in the clear!)
• :port - the TCP port to use for the SSH daemon. Defaults to 22.
• :subsystems - a list of SSH subsystems specs to start. Defaults to SFTP and ssh_subsystem_fwup
• :system_dir - where to find host keys
• :shell - the language of the shell (:elixir, :erlang, or :disabled). Defaults to :elixir.
• :exec - the language to use for commands sent over ssh (:elixir, :erlang, or :disabled). Defaults to :elixir.
• :iex_opts - additional options to use when starting up IEx
• :daemon_option_overrides - additional options to pass to :ssh.daemon/2. These take precedence and are unchecked.

Authentication

It's possible to set up a number of authentication strategies with the Erlang SSH daemon. Currently, only simple public key and username/password authentication setups are supported by :nerves_ssh. Both of them work fine for getting started. As needs become more sophisticated, you can pass options to :daemon_option_overrides.

Public key authentication

Public ssh keys can be included in the config.exs so that matching clients can connect. These come from files like your ~/.ssh/id_rsa.pub or ~/.ssh/id_ecdsa.pub that were created when you created your ssh keys. If you haven't done this, the following article may be helpful. Here's an example:

config :nerves_ssh,
  authorized_keys: [
    "ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBCdMwNo0xOE86il0DB2Tq4RCv07XvnV7W1uQBlOOE0ZZVjxmTIOiu8XcSLy0mHj11qX5pQH3Th6Jmyqdj",
    "ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAACAQCaf37TM8GfNKcoDjoewa6021zln4GvmOiXqW6SRpF61uNWZXurPte1u8frrJX1P/hGxCL7YN3cV6eZqRiF"
  ]

Here's another way that may work well for you that avoids needing to commit your keys:

config :nerves_ssh,
  authorized_keys: [
    File.read!(Path.join(System.user_home!, ".ssh/id_rsa.pub"))
  ]

Username/password authentication

The SSH console uses public key authentication by default, but it can be configured for usernames and passwords via the :user_passwords key. This has the form [{"username", "password"}, ...]. Keep in mind that passwords are stored in the clear. This is not recommended for most situations.

config :nerves_ssh,
  user_passwords: [
    {"username", "password"}
  ]

Goals

• Support public key authentication
• Support username/password authentication
• Device generated server certificate and key
• Device generated username/password