Server Configuration Guide

Configuration File Locations

🐧 Linux/macOS/BSD

/etc/sysmanage.yaml

🪟 Windows

C:\ProgramData\SysManage\sysmanage.yaml

🛠️ Development

sysmanage-dev.yaml (in project root)

Basic Configuration

API Server Settings

api:
  host: "localhost"           # Server bind address
  port: 6443                  # API server port (HTTPS if certificates available)
  certFile: ""                # SSL certificate file path (optional)
  chainFile: ""               # SSL certificate chain file path (optional)
  keyFile: ""                 # SSL private key file path (optional)

📝 Notes

Host binding: Use 0.0.0.0 for external access, localhost for local only
SSL certificates: If not provided, server falls back to HTTP
Port selection: Ensure the port is not in use by other services

Database Configuration

database:
  user: "sysmanage"           # PostgreSQL username
  password: "abc123"          # PostgreSQL password (CHANGE FOR PRODUCTION!)
  host: "localhost"           # Database server hostname
  port: 5432                  # PostgreSQL port
  name: "sysmanage"           # Database name

⚠️ Security Warning

The example password abc123 is for development only. Always use strong passwords in production!

Web UI Settings

webui:
  host: "localhost"           # Frontend server bind address
  port: 7443                  # Frontend server port (HTTPS if certificates available)

Security Configuration

Core Security Settings

security:
  password_salt: "YOUR_BASE64_SALT"      # Base64-encoded password salt
  admin_userid: "admin@yourdomain.com"   # Default admin user email
  admin_password: "YOUR_ADMIN_PASSWORD"  # Strong admin password
  jwt_secret: "YOUR_JWT_SECRET"          # JWT signing secret
  jwt_algorithm: "HS256"                 # JWT algorithm
  jwt_auth_timeout: 6000                 # Auth token timeout (seconds)
  jwt_refresh_timeout: 60000             # Refresh token timeout (seconds)

🔐 Generating Secure Values

# Generate password salt (32 bytes)
openssl rand -base64 32

# Generate JWT secret (32 bytes)
openssl rand -base64 32

# Example strong admin password (change this!)
openssl rand -base64 16

Password Policy Configuration

security:
  password_policy:
    min_length: 8                        # Minimum password length
    max_length: 128                      # Maximum password length
    require_uppercase: true              # Require uppercase letters
    require_lowercase: true              # Require lowercase letters
    require_numbers: true                # Require numbers
    require_special: true                # Require special characters
    special_characters: "!@#$%^&*()_+-=[]{}|;:,.<>?"  # Allowed special chars
    min_character_types: 3               # Minimum character types required
    prevent_username_in_password: true   # Prevent username in password

📝 Password Policy Notes

Real-time validation: Policies are enforced in both frontend and backend
Multi-language: Error messages available in all 14 supported languages
Flexible requirements: Adjust policies to meet your organization's needs

Email Configuration

SMTP Settings

email:
  enabled: true                         # Enable/disable email functionality

  smtp:
    host: "smtp.gmail.com"              # SMTP server hostname
    port: 587                           # SMTP port (587 for STARTTLS, 465 for SSL)
    use_tls: true                       # Enable STARTTLS
    use_ssl: false                      # Enable SSL/TLS (for port 465)
    username: "your-email@gmail.com"    # SMTP authentication username
    password: "your-app-password"       # SMTP authentication password
    timeout: 30                         # Connection timeout (seconds)

  from_address: "noreply@yourdomain.com"  # Default sender email
  from_name: "SysManage System"           # Default sender name

  templates:
    subject_prefix: "[SysManage]"         # Email subject prefix

📧 Common SMTP Configurations

email:
  smtp:
    host: "smtp.gmail.com"
    port: 587
    use_tls: true
    use_ssl: false
    username: "your-email@gmail.com"
    password: "your-16-digit-app-password"

Note: Requires 2FA and App Password. Visit Google App Passwords for setup.

email:
  smtp:
    host: "smtp-mail.outlook.com"
    port: 587
    use_tls: true
    use_ssl: false
    username: "your-email@yourdomain.com"
    password: "your-password"

email:
  smtp:
    host: "mail.yourdomain.com"
    port: 587
    use_tls: true
    use_ssl: false
    username: "your-email@yourdomain.com"
    password: "your-password"

email:
  smtp:
    host: "localhost"
    port: 25
    use_tls: false
    use_ssl: false
    username: ""    # Empty for localhost/no-auth
    password: ""    # Empty for localhost/no-auth

Certificate Management

Certificate Storage

certificates:
  path: "/etc/sysmanage/certs/"         # Certificate storage directory

  # Server certificates for HTTPS
  server_cert: "server.crt"             # Server certificate filename
  server_key: "server.key"              # Server private key filename

  # CA certificates for mTLS
  ca_cert: "ca.crt"                     # CA certificate filename
  ca_key: "ca.key"                      # CA private key filename

🔒 Required Permissions

Certificate directory: 0755 (owner rwx, group/others rx)
Private keys: 0600 (owner read/write only)
Certificates: 0644 (owner rw, others read)

mTLS Configuration

Mutual TLS settings are automatically managed by the server. When hosts are approved, client certificates are generated and stored in the certificate directory.

🔄 mTLS Workflow

Host Registration: Agent registers with pending status
Manual Approval: Administrator approves host in web interface
Certificate Generation: Server generates unique client certificate
Secure Authentication: Subsequent connections use mTLS

Advanced Features

Agent Discovery Service

discovery:
  enabled: true                         # Enable UDP discovery service
  port: 31337                           # UDP discovery port
  announcement_port: 31338              # UDP announcement port
  announcement_interval: 30             # Seconds between announcements

📡 Discovery Service

Allows agents to automatically discover and configure themselves with available servers on the network.

Logging Configuration

logging:
  level: "INFO"                         # DEBUG, INFO, WARNING, ERROR, CRITICAL
  file: "/var/log/sysmanage/server.log" # Log file path (optional)
  format: "detailed"                    # Log format: simple, detailed, json
  max_size: "10MB"                      # Maximum log file size
  backup_count: 5                       # Number of backup log files

Performance Tuning

performance:
  workers: 4                            # Number of worker processes
  max_connections: 1000                 # Maximum concurrent connections
  keepalive_timeout: 30                 # Keep-alive timeout (seconds)
  websocket_timeout: 300                # WebSocket timeout (seconds)

  # Database connection pooling
  db_pool_size: 10                      # Database connection pool size
  db_max_overflow: 20                   # Maximum overflow connections

File Permissions and Security

Required Directory Structure

# Create required directories with proper permissions
sudo mkdir -p /etc/sysmanage/certs
sudo mkdir -p /var/log/sysmanage

# Set ownership (replace 'sysmanage' with your service user)
sudo chown -R sysmanage:sysmanage /etc/sysmanage
sudo chown -R sysmanage:sysmanage /var/log/sysmanage

# Set permissions
sudo chmod 755 /etc/sysmanage
sudo chmod 755 /etc/sysmanage/certs
sudo chmod 755 /var/log/sysmanage
sudo chmod 600 /etc/sysmanage.yaml

🛡️ Security Checklist

✅ Configuration file is readable only by service user
✅ Certificate directory has restricted access
✅ Private keys are protected with 0600 permissions
✅ Strong passwords and secrets are used
✅ JWT secrets are regularly rotated
✅ Database credentials are unique and strong

Environment Variables

Configuration can also be set via environment variables (overrides YAML file):

# Database configuration
export SYSMANAGE_DB_HOST="localhost"
export SYSMANAGE_DB_PORT="5432"
export SYSMANAGE_DB_USER="sysmanage"
export SYSMANAGE_DB_PASSWORD="your_password"
export SYSMANAGE_DB_NAME="sysmanage"

# API configuration
export SYSMANAGE_API_HOST="0.0.0.0"
export SYSMANAGE_API_PORT="6443"

# Security configuration
export SYSMANAGE_JWT_SECRET="your_jwt_secret"
export SYSMANAGE_ADMIN_PASSWORD="your_admin_password"

Testing Configuration

Validation Steps

Configuration Syntax:

# Test YAML syntax
python -c "import yaml; yaml.safe_load(open('/etc/sysmanage.yaml'))"

Database Connection:

# Test database connectivity
PGPASSWORD=your_password psql -U sysmanage -d sysmanage -h localhost -c "SELECT 1;"

Email Configuration:
Use the Settings → Integrations page in the web interface to test email configuration.

SSL Certificates:

# Verify certificate validity
openssl x509 -in /etc/sysmanage/certs/server.crt -text -noout