Kaginawa (Japanese: 鉤縄) is a remote maintenance and data collection software designed for IoT gateways.

• SSH tunneling to pass through NATs and firewalls
• Automatic port assignment and reporting
• Device identification using physical MAC address
• Basic metrics collection and alive monitoring
• Scalable and fault tolerant design
• Automatic update

Note for ARM-based platforms:

• Kaginawa server (data collection)
• OpenSSH Server (ssh sockets)

Default configuration file name is kaginawa.json.

Minimum configuration:

{
  "api_key": "xxx",
  "server": "xxx.herokuapp.com"
}

Sample configuration for payload uploading:

{
  "api_key": "xxx",
  "server": "xxx.herokuapp.com",
  "ssh_enabled": false,
  "payload_command": "curl https://api.ipify.org?format=json"
}

Support status and configuration default values:

(*) df command is required.

Support status and configuration default values:

(*) lsusb command is required.

Support status and configuration default values:

(*) hcitool command is required.

Default values of update_command configuration parameter:

Support status and configuration default values:

• Go v1.13 or higher
• (Optional) GNU Make

Sample unit file is available at kaginawa.service.

Usage:

$ wget https://raw.githubusercontent.com/kaginawa/kaginawa/master/kaginawa.service
// review and edit file content
$ mv kaginawa.service /etc/systemd/system/
$ sudo systemctl enable kaginawa
$ sudo service kaginawa start

Example user creation and setup operation:

$ sudo useradd -d /opt/kaginawa -m kaginawa
$ sudo -su kaginawa
$ cd /opt/kaginawa
$ wget https://kaginawa.github.io/kaginawa.<PLATFORM>.bz2
$ bunzip kaginawa.<PLATFORM>.bz2
$ mv kaginawa.<PLATFORM> kaginawa
$ chmod +x kaginawa
$ vi kaginawa.json
// create configuration file (api_key and server are required)

Recommended sudo configuration (/etc/sudoers or /etc/sudoers.d/90-kaginawa):

kaginawa ALL=(ALL) NOPASSWD: /sbin/reboot, /usr/sbin/service

$ sudo useradd -m -s /bin/false kaginawa
$ sudo -su kaginawa
$ ssh-keygen
$ cd ~/.ssh
$ ssh-keygen -f remote
$ cat remote.pub >> authorized_keys
$ chmod 600 authorized_keys
$ cat remote
// Copy private key and paste to kagiana-server's admin screen

NOTE: A login shell is not required for tunneling connections. Use /bin/false to reduce the risk of server hijacking.

Each SSH session consumes file discriptor on the filesystem. We recommend to increase the limit of number of file discriptors when connecting large number of nodes.

/etc/security/limits.conf:

#<domain> <type> <item> <value>
* hard nofile 64000
* soft nofile 64000

If you using kaginawa with root user (not recommended), write following configuration:

#<domain> <type> <item> <value>
root hard nofile 64000
root soft nofile 64000

Each SSH session consumes a lot of memory due to the stack size overhead of processes but do not need to keep inactive sessions in memory. We recommend to create or increase swap space and enable it.

$ sudo fallocate -l 8G /swapfile
$ sudo chmod 600 /swapfile
$ sudo mkswap /swapfile
$ sudo swapon /swapfile

NOTE: If fallocate doesn't work, try sudo dd if=/dev/zero of=/swapfile count=8192 bs=1M (inefficient but reliable)

/etc/fstab:

/swapfile none swap sw 0 0

Kaginawa licensed under the BSD 3-clause license.

• mikan