Skip to content

🧾 Import Devices from CSV (Bash Script)

This page explains how to use the CSV importer script to create devices one by one through the API.

The script reads a CSV file and calls:

POST /api/v1/devices

For each row, you must provide exactly one authentication method:

  • password OR
  • private_key_file (the script converts it to private_key_b64 automatically)

🔐 Authentication Methods and SSH Key Handling

SingleJump supports two authentication methods when registering a device:

  • Password-based authentication (recommended)
  • SSH private key authentication (without passphrase)

Providing an SSH password is the preferred and most secure approach when adding a device.

When a password is supplied, SingleJump will:

  • Generate a dedicated SSH key pair exclusively for that device
  • Upload the public key automatically to the device using the provided password
  • Use the generated private key for all future connections

This design ensures that:

  • Each device has its own unique private key
  • Keys are isolated per device, improving security and auditability
  • No existing SSH keys are reused or shared across devices

🔒 Password Handling (Important)

  • The SSH password is never stored by SingleJump
  • The password is used only once, during device registration
  • Its sole purpose is to upload the generated public key to the device
  • After the public key is installed, all access is performed using the generated SSH key

🆕 Alternative: Providing a Private Key (No Passphrase)

If you choose to provide your own SSH private key:

  • The key must not be protected with a passphrase
  • The key should be dedicated to automation
  • Existing personal or shared keys should not be reused

To avoid weakening existing security, it is recommended to generate a new private key specifically for SingleJump automation, rather than removing the passphrase from an existing key.

Generate a new private key (ED25519, no passphrase)

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_singlejump -N "" -C "singlejump@automation"

This will create a new key pair without affecting existing SSH keys.

✅ Requirements

  • bash
  • curl
  • base64

The script works on Linux and macOS.

📥 Download the Script

The CSV import script can be downloaded directly from:

https://singlejump.com/scripts/import_devices.sh

After downloading, make it executable:

chmod +x import_devices.sh

It is recommended to review the script before running it, especially when handling credentials or private keys.

📁 CSV Format

The CSV must include a header with the following columns:

name,hostname,ip,port,username,description,password,private_key_file

Column description

  • name: Device name
  • hostname: Hostname or DNS name
  • ip: IP address
  • port: SSH port
  • username: SSH username
  • description: Free text description
  • password: SSH password (optional)
  • private_key_file: Path to a private key file (optional)

Authentication rule

Exactly one of the following must be provided per row:

  • password
  • private_key_file

Rows with none or both will be rejected.

🧪 Example CSV

name,hostname,ip,port,username,description,password,private_key_file
web01,web01.local,192.168.4.120,22,deploy01,Primary web server,SuperSecret123,
web02,web02.local,192.168.4.121,22,deploy02,Worker node,,/home/deploy/.ssh/id_ed25519

🚀 Running the Script

1) Make the script executable

chmod +x import_devices.sh

2) Configure environment variables

export API_URL="https://login.yourdomian.com/api/v1/devices"
export API_KEY="YOUR_API_KEY_HERE"

3) Execute

./import_devices.sh devices.csv

🔐 Using SSH Private Keys

If private_key_file is present, the script will:

  1. Read the key from disk
  2. Encode it as base64 (single line)
  3. Send it as private_key_b64 in the request body

This allows the API to remain JSON-only.

⚙️ Optional Environment Variables

Variable Default Description
INSECURE_TLS 1 Allow self-signed TLS (curl -k)
DRY_RUN 0 Print payloads without calling the API
SLEEP_SECONDS 0 Delay between API calls
CURL_TIMEOUT 20 Request timeout in seconds

🧯 Troubleshooting

Validation errors (422)

The API response body is printed for each failed row.