nssh

README

nssh

SSH client for SORACOM Napter. You can easily open an SSH connection with your subscriber's name.

Napter is an on-demand networking service for devices using Soracom Air for Cellular SIM cards, which enables you to quickly and securely access your devices remotely. Napter allows you to perform remote maintenance, troubleshooting, or other typical remote access tasks, without setting up any relay servers or installing agent software on the device.

Tested Platform

At this moment, the client is only tested on folloing platforms. It can be built for other Linux distributions and Windows but might not work due to x/crypto/ssh.readVersion hang, etc. PR's welcome.

• DebianGNU/Linux 11 (bullseye) aarch64
• macOS 13.4.1 (Ventura) arm64

Install

1. Download the archive for your platform and architecture from Releases section.
2. Unpack the archive.
3. Move the executable to one of your PATH directories.

Or you can build executable from the source:

$ git clone https://github.com/0x6b/nssh
$ cd nssh
$ make # and you'll get `nssh` under the root directory

Usage

One-time Setup

1. Create a SAM user with following permission:

   {
     "statements": [
       {
         "api": [
           "Subscriber:listSubscribers",
           "PortMapping:listPortMappingsForSubscriber",
           "PortMapping:createPortMapping"
         ],
         "effect": "allow"
       }
     ]
   }
   

2. Generate authentication key for the user.
3. Save the authentication information at $HOME/.soracom/nssh.json, or %HOMEPATH%\.soracom\ssh.json as below.

   {
     "coverageType": "jp", // default coverage, specify "g" for global
     "authKeyId": "keyId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
     "authKey": "secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   }
   

4. Name your desired SIM at SORACOM User Console.

Connect

$ nssh connect pi@your-sim-name

You can specify coverage type, profile name, port number, connection duration, or identity file for SSH public key authentication. See nssh connect --help.

• Override coverage type, jp or global:

  $ nssh --coverage-type global connect pi@your-sim-name
  

• Use another profile under $HOME/.soracom/ directory, without extension .json:

  $ nssh --profile-name default connect pi@your-sim-name
  

• Use public key authentication:

  $ nssh connect pi@your-sim-name -i ~/.ssh/id_rsa
  

• Specify another port number and connection duration:

  $ nssh connect pi@your-sim-name --port 2222 --duration 120
  

Details

Global help:

$ nssh --help
nssh -- SSH client for SORACOM Napter

Usage:
  nssh [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  connect     Connect to specified subscriber via SSH.
  help        Help about any command
  list        List port mappings for specified subscriber. If no subscriber name is specified, list all port mappings.
  version     Show version

Flags:
      --coverage-type string   Specify coverage type, "g" for Global, "jp" for Japan
  -h, --help                   help for nssh
      --profile-name string    Specify SORACOM CLI profile name (default "nssh")

Use "nssh [command] --help" for more information about a command.

Help for connect sub-command:

$ nssh connect --help
Create port mappings for specified subscriber and connect via SSH. If <user>@ is not specified, "pi" will be used as default. Quote with " if name contains spaces or special characters.

Usage:
  nssh connect [<user>@]<subscriber name> [flags]

Aliases:
  connect, c

Flags:
  -d, --duration int      Specify session duration in minutes (default 60)
  -h, --help              help for connect
  -i, --identity string   Specify a path to file from which the identity for public key authentication is read
  -p, --port int          Specify port number to connect (default 22)

Global Flags:
      --coverage-type string   Specify coverage type, "g" for Global, "jp" for Japan
      --profile-name string    Specify SORACOM CLI profile name (default "nssh")

Help for list sub-command:

$ nssh list --help
List port mappings for specified subscriber. If no subscriber name is specified, list all port mappings.

Usage:
  nssh list [subscriber name] [flags]

Aliases:
  list, l

Flags:
  -h, --help   help for list

Global Flags:
      --coverage-type string   Specify coverage type, "g" for Global, "jp" for Japan
      --profile-name string    Specify SORACOM CLI profile name (default "nssh")

References

• Japanese
  • IoT プラットフォーム 株式会社ソラコム
  • SORACOM Napter とは | ユーザーガイド | SORACOM Developers
• English
  • Soracom | Cellular IoT Cloud Connectivity
  • Soracom Napter Overview | SORACOM Developers

License

MIT. See LICENSE for details.

Privacy

This program will send requests to following services:

• https://checkip.amazonaws.com/, to determine your global IP address.
• https://g.api.soracom.io (Global coverage) or https://api.soracom.io (Japan coverage), to use SORACOM services

Other than that, the program does not send user action/data to any server. Please consult each provider's privacy notices.

• AWS Privacy Notice
• Privacy Policy | Soracom

---

Enjoy remote connection with SORACOM Napter!

Documentation

Index

• Constants
• func GetIP() (net.IP, error)
• type PortMapping
  • func (pm PortMapping) String() string
• type SoracomClient
  • func NewSoracomClient(coverageType, profileName string) (*SoracomClient, error)
  • func (c *SoracomClient) Connect(login, identity string, portMapping *PortMapping) error
  • func (c *SoracomClient) CreatePortMappingsForSubscriber(subscriber Subscriber, port, duration int) (*PortMapping, error)
  • func (c *SoracomClient) FindPortMappings() ([]PortMapping, error)
  • func (c *SoracomClient) FindPortMappingsForSubscriber(subscriber Subscriber) ([]PortMapping, error)
  • func (c *SoracomClient) FindSubscribersByName(name string) ([]Subscriber, error)
  • func (c *SoracomClient) GetSubscriber(imsi string) (*Subscriber, error)
• type Subscriber
  • func (s Subscriber) String() string

Constants

const SIGWINCH = syscall.SIGWINCH

Functions

func GetIP

func GetIP() (net.IP, error)

GetIP gets current global IP address using https://checkip.amazonaws.com/

Types

type PortMapping

type PortMapping struct {
	Duration    int    `json:"duration"`    // duration in seconds
	Endpoint    string `json:"endpoint"`    // SORACOM Napter endpoint
	Hostname    string `json:"hostname"`    // SORACOM Napter hostname
	IPAddress   string `json:"ipAddress"`   // SORACOM Napter IP address
	Port        int    `json:"port"`        // SORACOM Napter port number
	TLSRequired bool   `json:"tlsRequired"` // is TLS required
	Destination struct {
		Imsi string `json:"imsi"` // target IMSI
		Port int    `json:"port"` // target port
	} `json:"destination"`
	Source struct {
		IPRanges []string `json:"ipRanges"` // permitted source CIDRs
	} `json:"source"`
}

A PortMapping represents SORACOM Napter port mapping

func (PortMapping) String

func (pm PortMapping) String() string

type SoracomClient

type SoracomClient struct {
	APIKey   string // API key
	Token    string // API token
	Client   *http.Client
	Endpoint string
}

A SoracomClient represents an API client for SORACOM API. See https://developers.soracom.io/en/docs/tools/api-reference/ or https://dev.soracom.io/jp/docs/api_guide/

func NewSoracomClient

func NewSoracomClient(coverageType, profileName string) (*SoracomClient, error)

NewSoracomClient returns new SoracomClient for caller

func (*SoracomClient) Connect

func (c *SoracomClient) Connect(login, identity string, portMapping *PortMapping) error

Connect connects to specified port mapping with login name and identity. If identity is specified, use it for public key authentication. If not, use password authentication instead.

func (*SoracomClient) CreatePortMappingsForSubscriber

func (c *SoracomClient) CreatePortMappingsForSubscriber(subscriber Subscriber, port, duration int) (*PortMapping, error)

CreatePortMappingsForSubscriber creates port mappings for specified subscriber, port, and duration

func (*SoracomClient) FindPortMappings

func (c *SoracomClient) FindPortMappings() ([]PortMapping, error)

FindPortMappings finds all port mappings

func (*SoracomClient) FindPortMappingsForSubscriber

func (c *SoracomClient) FindPortMappingsForSubscriber(subscriber Subscriber) ([]PortMapping, error)

FindPortMappingsForSubscriber finds port mappings for specified subscriber

func (*SoracomClient) FindSubscribersByName

func (c *SoracomClient) FindSubscribersByName(name string) ([]Subscriber, error)

FindSubscribersByName finds subscribers which has the specified name

func (*SoracomClient) GetSubscriber

func (c *SoracomClient) GetSubscriber(imsi string) (*Subscriber, error)

GetSubscriber gets subscriber information for specified IMSI

type Subscriber

type Subscriber struct {
	Imsi          string `json:"imsi"`         // IMSI of the subscriber
	Subscription  string `json:"subscription"` // subscription e.g. plan01s, plan-D
	Type          string `json:"type"`         // speed class e.g. s1.4xfast
	SessionStatus struct {
		Online bool `json:"online"` // represents subscriber is online or not
	} `json:"sessionStatus"`
	Tags struct {
		Name string `json:"name,omitempty"` // name of the subscriber
	} `json:"tags"`
}

A Subscriber represents a SORACOM IoT SIM

func (Subscriber) String

func (s Subscriber) String() string