Backup and Restore CLI

Command-line tool for automated directory backup with real-time change detection, built for the Koneksi Secure Digital Storage Solution.

Complete How-To Guide

Features

• Real-time Monitoring: Automatically detects changes in specified directories

• Single File Backup: Backup individual files on demand

• Directory Compression: Compress entire directories into tar.gz archives before backup

• Concurrent Backups: Efficiently backs up multiple files in parallel

• Smart Detection: Only backs up files that have actually changed (using checksums)

• Compression Support: Optional gzip/zlib compression to save storage space

• Encryption Support: AES-256-GCM encryption for secure backups with password protection

• Large File Support: Handle files up to 2GB with automatic compression recommendations

• Database Tracking: SQLite database tracks all backup history and metadata

• Comprehensive Reporting: Generates detailed JSON reports for each backup session

• Full Restore Capability: Restore backed up files from manifest files

• Auto-extraction: Automatically extract tar.gz archives after restore

• Auto-decryption: Automatically decrypt encrypted files after restore

• Configurable: Flexible configuration for directories, exclusions, and performance

Prerequisites

• Go 1.19 or higher (for building from source)

• Valid email address for registration

• Internet connection

• Operating System: Linux, macOS, or Windows

Installation

Option 1: Build from Source

Download the latest release for your platform from the releases page.

# Clone the repository
git clone https://github.com/koneksi-tech/koneksi-backup-cli.git
cd koneksi-backup-cli

# Build the CLI
make build

# Or install globally
make install

Option 2: Download Pre-built Binary

Download the latest release for your platform from the releases page.

If you already have a verified Koneksi account, skip to Step 4: Configuration to set up your environment. Otherwise, follow the steps below to register, verify, and create API keys for programmatic access.

Step 1: User Registration

First, you need to create an account with Koneksi.

koneksi-backup auth register \
    --first-name "John" \
    --last-name "Doe" \
    --email "[e-mail]" \
    --password "StrongPassword123!"

Expected Output:

Registration successful!
User ID: usr_1234567890
Email: [e-mail]

IMPORTANT: A verification code has been sent to your email.

Next steps:
1. Check your email for the verification code
2. Login: koneksi-backup auth login -e [e-mail] -p <your-password>
3. Verify: koneksi-backup auth verify <verification-code> -t <access-token>

Step 2: Account Verification

2.1 Login to Get Access Token

koneksi-backup auth login \
    --email "[e-mail]" \
    --password "StrongPassword123!"

Expected Output:

Login successful!

Access Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Use this token to create/revoke API keys:
  koneksi-backup auth create-key "My API Key" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh Token (save for later use):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2.2 Verify Your Account

Check your email for the 6-digit verification code, then:

koneksi-backup auth verify "123456" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Expected Output:

Account verified successfully!
Email: [e-mail]
Verified: true

You can now create API keys using:
  koneksi-backup auth create-key "My API Key" -t <your-access-token>

Step 3: Creating API Keys

API keys are used for programmatic access to the backup service.

koneksi-backup auth create-key "My Backup Service" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Expected Output:

API Key 'My Backup Service' created successfully!

Client ID:
id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE

Client Secret (save this, it won't be shown again):
sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U

To use these credentials with koneksi-backup:
  export KONEKSI_API_CLIENT_ID=<client-id>
  export KONEKSI_API_CLIENT_SECRET=<client-secret>

Or add them to your config file (~/.koneksi-backup/config.yaml)

Important: Save the Client ID and Client Secret immediately. The Client Secret cannot be retrieved later.

Step 4: Configuration

4.1 Set Environment Variables (Quick Start)

export KONEKSI_API_CLIENT_ID="id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE"
export KONEKSI_API_CLIENT_SECRET="sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U"

4.2 Create Configuration File (Recommended)

# Initialize configuration
koneksi-backup init

This creates ~/.koneksi-backup/config.yaml. Edit it to add your credentials:

api:
  base_url: "https://uat.koneksi.co.kr"
  client_id: "id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE"
  client_secret: "sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U"
  directory_id: ""  # Leave empty to auto-create
  timeout: 30
  retry_count: 3

backup:
  directories:
    - "/home/john/documents"
    - "/home/john/projects"
  exclude_patterns:
    - "*.tmp"
    - "*.log"
    - ".git"
    - "node_modules"
  check_interval: 300
  max_file_size: 1073741824
  concurrent: 5
  compression:
    enabled: false
    level: 6
    format: "gzip"
  encryption:
    enabled: false
    password: ""  # Or use KONEKSI_BACKUP_ENCRYPTION_PASSWORD env var

Step 5: Performing Backups

5.1 One-Time Backup of a Single File

koneksi-backup backup /path/to/important-file.pdf

5.2 Backup a Directory

koneksi-backup backup /home/john/documents

5.3 Backup Directory as Compressed Archive

For faster uploads of directories with many files:

koneksi-backup backup /home/john/projects/my-app --compress-dir

5.4 Continuous Monitoring (Daemon Mode)

Start the backup service to continuously monitor directories:

koneksi-backup run

Expected Output for Backup:

Starting backup of: /home/john/documents
Backing up file: report.pdf (size: 2458624 bytes)
Backing up file: presentation.pptx (size: 5242880 bytes)
Queued 15 files for backup
Waiting 20s for backups to complete...

Backup Report Summary
====================
Report ID: backup-20250115-143022
Duration: 18.5s
Total Files: 15
Successful: 15
Failed: 0
Total Size: 24.5 MB

Step 6: Restoring Files

6.1 Create a Restore Manifest

First, find your backup report:

ls ./reports/

Create a manifest from the report:

koneksi-backup manifest ./reports/backup-20250115-143022.json restore-manifest.json

6.2 Restore Files

koneksi-backup restore restore-manifest.json /home/john/restored-files

6.3 Restore with Auto-Extraction

If you backed up compressed directories:

koneksi-backup restore restore-manifest.json /home/john/restored-files --auto-extract

Expected Output:

Starting restore from manifest: restore-manifest.json
Target directory: /home/john/restored-files
Restoring: report.pdf (2.4 MB)
Restoring: presentation.pptx (5.0 MB)
Progress: 15/15 files

Restore completed:
- Total files: 15
- Restored: 15
- Failed: 0
- Duration: 12s

Encryption

The Koneksi Backup CLI supports AES-256-GCM encryption to secure your files before uploading to the cloud. This adds an extra layer of security for sensitive data.

Backup with Encryption

5.5 Encrypt Files During Backup

# Backup with encryption using command line password
koneksi-backup backup /path/to/sensitive-data --encrypt --encrypt-password "MySecretPass123"

# Backup with encryption using environment variable
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="MySecretPass123"
koneksi-backup backup /path/to/sensitive-data --encrypt

# Combine compression and encryption for directories
koneksi-backup backup /home/john/confidential --compress-dir --encrypt --encrypt-password "MySecretPass123"

Expected Output:

Starting backup of: /home/john/confidential
Compressing directory before backup...
Directory compressed to /tmp/backup-123456.tar.gz (size: 5242880 bytes)
Encryption is enabled for this backup
Encrypting file before backup...
File encrypted (size: 5243904 bytes)
Backup completed successfully

Restore with Decryption

6.4 Restore and Decrypt Files

# Restore with decryption using command line password
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt --decrypt-password "MySecretPass123"

# Restore with decryption using environment variable
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="MySecretPass123"
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt

# Combine decryption and extraction
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt --auto-extract --decrypt-password "MySecretPass123"

Expected Output:

Starting restore from manifest: restore-manifest.json
Target directory: /home/john/restored-files
Restoring: confidential-data.tar.gz.enc (5.0 MB)
Progress: 1/1 files

Restore completed:
- Total files: 1
- Restored: 1
- Failed: 0
- Duration: 3s

Checking for encrypted files to decrypt...
Decrypting confidential-data.tar.gz.enc...
Decrypted and removed confidential-data.tar.gz.enc

Decrypted 1 file(s)

Checking for tar.gz files to extract...
Extracting confidential-data.tar.gz...
Extracted and removed confidential-data.tar.gz

Extracted 1 archive(s)

Configuration-Based Encryption

You can enable encryption by default in your configuration file:

backup:
  encryption:
    enabled: true
    password: "MySecretPass123"  # Or leave empty and use env var

Security Best Practices for Encryption

1. Strong Passwords: Use long, complex passwords with mixed characters

2. Password Storage: Store passwords in environment variables or secure password managers

3. Never Commit Passwords: Don't commit passwords to version control

4. Rotate Passwords: Regularly change encryption passwords for enhanced security

5. Backup Passwords: Ensure you have a secure backup of your encryption passwords

Example: Encrypting Sensitive Financial Data

# Set up encryption password securely
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="$(openssl rand -base64 32)"
echo "Save this password securely: $KONEKSI_BACKUP_ENCRYPTION_PASSWORD"

# Backup financial records with encryption
koneksi-backup backup ~/financial-records --compress-dir --encrypt

# Later, restore with the same password
koneksi-backup restore financial-manifest.json ~/restored-financials --decrypt --auto-extract

Advanced Features

Directory Management

List All Backup Directories

koneksi-backup dir list

Create a New Directory

koneksi-backup dir create "Project Backups" -d "Backup directory for all projects"

Large File Handling

For files larger than 100MB, always compress first:

# Compress large file
gzip large-database.sql

# Backup compressed file
koneksi-backup backup large-database.sql.gz

Complete Example Workflow

Here's a complete example from registration to restore:

# Steps 1-3 is optional if you already have a Koneksi Verified Account.

# 1. Register
koneksi-backup auth register \
    --first-name "Jane" \
    --last-name "Smith" \
    --email "[e-mail]" \
    --password "SecurePass123!"

# 2. Login
koneksi-backup auth login \
    --email "[e-mail]" \
    --password "SecurePass123!"
# Copy the access token

# 3. Verify account (check email for code)
koneksi-backup auth verify "654321" -t "access-token-here"

# 4. Create API key
koneksi-backup auth create-key "Production Backup" -t "access-token-here"
# Save the client ID and secret

# 5. Configure
export KONEKSI_API_CLIENT_ID="your-client-id"
export KONEKSI_API_CLIENT_SECRET="your-client-secret"

# 6. Backup important files with compression and encryption
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="SecureBackupPass456!"
koneksi-backup backup ~/important-docs --compress-dir --encrypt

# 7. Create restore manifest
koneksi-backup manifest ./reports/backup-*.json my-restore.json

# 8. Restore files to a new location with decryption and extraction
koneksi-backup restore my-restore.json ~/restored-docs --decrypt --auto-extract

Troubleshooting

Common Issues and Solutions

Authentication Errors

# Test your credentials
koneksi-backup dir list

If this fails, check that your environment variables or config file contain valid credentials.

Email Verification Issues

• Check spam folder for verification email

• Ensure you're using a valid email domain (gmail.com, outlook.com, etc.)

• Request a new verification code by logging in again

Large File Upload Failures

# Increase timeout in config
api:
  timeout: 300  # 5 minutes

# Or compress the file first
gzip large-file.bin
koneksi-backup backup large-file.bin.gz

Permission Denied Errors

Ensure you have read permissions on files you're backing up:

ls -la /path/to/backup/directory

Debug Mode

Run with debug logging for more information:

koneksi-backup backup /path/to/file --log-level debug

Best Practices

1. Regular Backups: Use daemon mode (koneksi-backup run) for continuous protection

2. Compress Large Files: Always compress files > 100MB before backup

3. Encrypt Sensitive Data: Use encryption for confidential files (financial, personal, business data)

4. Organize Directories: Create separate backup directories for different projects

5. Test Restores: Periodically test restoring files to ensure backups are working

6. Secure Credentials: Never commit API keys or encryption passwords to version control

7. Monitor Reports: Check backup reports regularly for any failures

8. Password Management: Use a password manager or secure vault for encryption passwords

Getting Help

• Built-in Help: koneksi-backup --help

• Command Help: koneksi-backup backup --help

• Report Issues: https://github.com/koneksi-tech/koneksi-backup-cli/issues

• Documentation: Check README.md for detailed configuration options

Next Steps

Now that you've completed the setup:

1. Configure automatic backups for your important directories

2. Set up a cron job for regular backup runs

3. Create backup policies for different types of data

4. Integrate with your existing backup workflows

---

Additional Resources

• GitHub Repository: https://github.com/koneksi-tech/backup-restore

• Issue Tracker: https://github.com/koneksi-tech/backup-restore/issues

• Releases: https://github.com/koneksi-tech/backup-restore/releases