CSV & JSON Formats

Import and export hosts using CSV (spreadsheet) or JSON (structured data) formats for bulk operations and backups.

CSV Format

Perfect for spreadsheet editing, bulk imports, and non-technical users.

CSV Structure

Required columns:

• name - Host display name
• host - IP address or hostname
• username - SSH username

Optional columns:

• port - Port number (default: 22)
• password - SSH password (leave empty if using keys)
• sshKeyId - SSH key ID from Xermius keychain
• group - Group name for organization

CSV Example

name,host,port,username,password,sshKeyId,group
Production Web,192.168.1.100,22,admin,,,Production
Dev Server,192.168.1.101,22,developer,dev_pass,,Development
Database,db.example.com,3306,dbadmin,db_secret,,Production
Staging API,staging.example.com,2222,ubuntu,,,Staging
Client Server,client.com,22,root,,key-abc-123,Clients

CSV Import

Step 1: Prepare CSV File

Create CSV in Excel, Google Sheets, or text editor:

Excel/Google Sheets:

1. Create table with column headers
2. Fill in host data
3. Export as CSV

Text Editor:

name,host,port,username,password,sshKeyId,group
Server 1,192.168.1.100,22,admin,,,Production
Server 2,192.168.1.101,22,admin,,,Production

Step 2: Import to Xermius

1. Open Xermius
2. Click NEW HOST → Import Hosts
3. Click CSV tab
4. Click Browse File and select your CSV
5. Preview hosts
6. Click Import

Step 3: Download Sample CSV

Not sure about format? Download a sample:

1. In Import dialog, CSV tab
2. Click Download Sample CSV
3. Edit the sample with your data
4. Import the edited file

CSV Export

Export All Hosts

1. Click NEW HOST → Export Hosts
2. Click CSV tab
3. Review the CSV output
4. Click Download File or Copy to Clipboard

Output example:

name,host,port,username,password,sshKeyId,group
Production Web,192.168.1.100,22,admin,,key-123,Production
Dev Server,192.168.1.101,22,developer,,,Development
Database Server,db.example.com,3306,dbadmin,,key-456,Production/Databases

Export Selected Hosts

1. Select specific hosts in dashboard
2. Right-click → Export Selected
3. Choose CSV format
4. Download or copy

CSV Use Cases

1. Bulk Import from Spreadsheet

1. Maintain host list in Google Sheets
2. Team members update sheet
3. Export as CSV
4. Import to Xermius
Perfect for: Teams managing many servers

2. Host Inventory Report

1. Export all hosts to CSV
2. Open in Excel
3. Create pivot tables
4. Analyze by group, username, port
Perfect for: Audits and documentation

3. Backup to Cloud Storage

1. Export to CSV weekly
2. Save to Dropbox/Google Drive
3. Version control with dates
4. Easy restore when needed
Perfect for: Regular backups

4. Migration Between Accounts

1. Export from old account (CSV)
2. Share file with team
3. Import to new accounts
4. Everyone has same hosts
Perfect for: Team onboarding

JSON Format

Structured data format for backups, version control, and programmatic access.

JSON Structure

[
  {
    "name": "Production Web Server",
    "host": "192.168.1.100",
    "port": 22,
    "username": "admin",
    "password": "",
    "sshKeyId": "key-abc-123",
    "group": "Production"
  },
  {
    "name": "Dev Server",
    "host": "192.168.1.101",
    "port": 22,
    "username": "developer",
    "password": "dev_pass",
    "sshKeyId": null,
    "group": "Development"
  }
]

JSON Fields

Field	Type	Required	Description
name	string	Yes	Host display name
host	string	Yes	IP or hostname
port	number	No	Port (default: 22)
username	string	Yes	SSH username
password	string	No	SSH password
sshKeyId	string/null	No	Keychain key ID
group	string	No	Group name

JSON Export

1. Click NEW HOST → Export Hosts
2. Click JSON tab
3. Review formatted JSON
4. Click Download File or Copy to Clipboard

Output:

[
  {
    "name": "production-web-01",
    "host": "192.168.1.100",
    "port": 22,
    "username": "admin",
    "password": "",
    "sshKeyId": "key-prod-web",
    "group": "Production/Web"
  },
  {
    "name": "staging-db",
    "host": "staging.example.com",
    "port": 3306,
    "username": "dbadmin",
    "password": "staging_pass",
    "sshKeyId": null,
    "group": "Staging/Database"
  }
]

JSON Use Cases

1. Version Control with Git

# Backup hosts to git
xermius export --format json > hosts.json
git add hosts.json
git commit -m "Update host configurations"
git push

Perfect for: Tracking changes over time

2. Automated Backups

#!/bin/bash
# Daily backup script
DATE=$(date +%Y%m%d)
xermius export --format json > "backup-$DATE.json"

Perfect for: Automated backup systems

3. API Integration

// Load hosts from JSON
const hosts = require('./xermius-hosts.json');

// Process hosts programmatically
hosts.forEach(host => {
  console.log(`Connecting to ${host.name}...`);
  // Your automation logic
});

Perfect for: DevOps automation

4. Configuration Management

1. Store JSON in config repo
2. CI/CD reads JSON
3. Automated deployments
4. Infrastructure as code
Perfect for: GitOps workflows

Format Comparison

Feature	CSV	JSON
Human Readable	✅ Very	⚠️ Moderate
Excel/Sheets	✅ Native	❌ Requires conversion
Version Control	⚠️ Text diffs	✅ Clear diffs
Programmatic	⚠️ Parsing needed	✅ Native
File Size	✅ Smaller	⚠️ Larger
Complex Data	❌ Limited	✅ Excellent
Non-tech Users	✅ Easy	❌ Technical

Advanced Examples

CSV with Special Characters

name,host,port,username,password,sshKeyId,group
"Production, Web Server",192.168.1.100,22,admin,,,Production
"Dev ""Test"" Server",192.168.1.101,22,dev,,,Development

Rules:

• Use quotes for names with commas
• Double quotes to escape quotes
• Keep it simple when possible

JSON with Nested Groups

[
  {
    "name": "web-01",
    "host": "192.168.1.100",
    "port": 22,
    "username": "admin",
    "group": "Production/Web/Frontend"
  },
  {
    "name": "api-01",
    "host": "192.168.1.101",
    "port": 22,
    "username": "admin",
    "group": "Production/API/Backend"
  }
]

Groups support nesting with / separator.

Bulk Import with Groups

CSV for organized import:

name,host,port,username,password,sshKeyId,group
web-01,192.168.1.100,22,admin,,,Production/Web
web-02,192.168.1.101,22,admin,,,Production/Web
api-01,192.168.1.102,22,admin,,,Production/API
api-02,192.168.1.103,22,admin,,,Production/API
db-01,192.168.1.104,3306,dbadmin,,,Production/Database
cache-01,192.168.1.105,6379,admin,,,Production/Cache

All hosts imported with proper group structure!

Troubleshooting

CSV Import Issues

Problem: "Missing required column"

Solution:

• Check first row has headers: name,host,username
• Verify spelling matches exactly
• No extra spaces in header names

Problem: "Invalid CSV format"

Solution:

• Check for unescaped commas in names
• Use quotes around values with special characters
• Verify file is actually CSV, not Excel format

Problem: "Some hosts skipped"

Solution:

• Check rows have all required fields
• Empty host or username = skipped
• Check for blank lines (remove them)

JSON Import Issues

Problem: "Invalid JSON format"

Solution:

• Validate JSON with online validator
• Check for missing commas between objects
• Verify brackets match: [ and ]
• Use proper quotes: " not ' or "

Problem: "Field type mismatch"

Solution:

• Port must be number: 22 not "22"
• Booleans are lowercase: true not True
• Null is: null not "null"

Security Best Practices

Handling Passwords

CSV/JSON files contain passwords in plain text!

Security measures:

✅ Don't commit to Git
✅ Encrypt files at rest
✅ Delete after import
✅ Use SSH keys instead
✅ Secure file permissions

Better approach:

name,host,port,username,password,sshKeyId,group
Server1,192.168.1.100,22,admin,,key-id-here,Production

Leave password empty, use sshKeyId field!

.gitignore for Backups

# Don't commit host backups
hosts-backup-*.csv
hosts-backup-*.json
*-passwords.csv
credentials.json

Encryption Example

Encrypt before storing:

# Export and encrypt
xermius export --format json > hosts.json
gpg -c hosts.json  # Creates hosts.json.gpg
rm hosts.json      # Remove plain text

# Decrypt when needed
gpg hosts.json.gpg  # Creates hosts.json
xermius import hosts.json
rm hosts.json       # Clean up

Tips & Best Practices

CSV Tips

✅ Use templates - Start with sample CSV
✅ Test small first - Import 2-3 hosts to verify format
✅ Remove passwords - Use SSH keys instead
✅ Consistent naming - Follow naming convention
✅ Document columns - Add comments in first row (delete before import)

JSON Tips

✅ Pretty print - Use formatted JSON (easier to read)
✅ Validate before import - Use JSON validator
✅ Include metadata - Add export date in filename
✅ Version control - Track changes in Git
✅ Backup regularly - Weekly exports

General Tips

✅ Backup before import - Export current hosts first
✅ Preview always - Check before confirming import
✅ Test connection - Verify a few hosts after import
✅ Organize immediately - Add groups, tags after import

Related Documentation

• 📚 Import/Export Overview
• 🔧 SSH Config Format
• 📁 Organize Hosts
• 🔑 SSH Key Management

---

Quick tip: For team collaboration, use CSV in shared Google Sheets. For personal backups, use JSON in Git!