Documentation > Administration > Host Account Management

Host Account Management

Create and manage user accounts and groups on remote hosts across all supported platforms.

Overview

SysManage provides centralized management of user accounts and groups on remote hosts. Create users and groups from the web interface without needing direct SSH access, with full support for platform-specific options across Linux, BSD, macOS, and Windows systems.

Key Features

  • Cross-Platform Support: Create users and groups on Linux, BSD, macOS, and Windows
  • Platform-Specific Options: Configure shell, home directory, UID/GID, and Windows-specific settings
  • Web Interface: Create accounts directly from the host detail page
  • Role-Based Access: Granular permissions for account and group management
  • Audit Logging: All account operations are logged for compliance
  • Privileged Mode Required: Agent must run with elevated privileges for account management

Supported Platforms

Linux Systems

User and group creation uses standard useradd and groupadd commands:

  • Ubuntu/Debian: useradd, groupadd
  • RHEL/CentOS/Fedora: useradd, groupadd
  • openSUSE: useradd, groupadd

BSD Systems

BSD platforms use their native account management tools:

  • FreeBSD: pw useradd, pw groupadd
  • OpenBSD: useradd, groupadd
  • NetBSD: useradd, groupadd

macOS

macOS uses Directory Services for account management:

  • dscl: Directory Services command line utility
  • createhomedir: Home directory creation

Windows

Windows uses native account management commands:

  • net user: Create and manage local user accounts
  • net localgroup: Create and manage local groups

User Account Operations

Creating a User Account

Create new user accounts on remote hosts through the web interface or API.

Create via Web Interface

  1. Navigate to the host detail page for the target system
  2. Locate the Users card in the host details
  3. Click the Add User button
  4. Fill in the required username and optional fields
  5. Click Create to submit the request
  6. The user list will update automatically after creation

User Creation Options

Option Description Platforms
username Username for the new account (required) All
full_name Full name or comment for the user All
home_directory Path to user's home directory Unix/Linux/BSD/macOS
shell Login shell (e.g., /bin/bash, /bin/zsh) Unix/Linux/BSD/macOS
create_home_dir Create home directory if it doesn't exist Unix/Linux/BSD/macOS
uid Specific user ID number Unix/Linux/BSD/macOS
primary_group Primary group name for the user Unix/Linux/BSD/macOS
password Initial password for the account Windows
password_never_expires Set password to never expire Windows
user_must_change_password Require password change on first login Windows
account_disabled Create account in disabled state Windows

Create via API

curl -X POST "https://your-server.example.com/api/v1/host/{host_id}/accounts" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "newuser",
       "full_name": "New User",
       "home_directory": "/home/newuser",
       "shell": "/bin/bash",
       "create_home_dir": true
     }'

Group Operations

Creating a Group

Create new groups on remote hosts through the web interface or API.

Create via Web Interface

  1. Navigate to the host detail page for the target system
  2. Locate the Groups card in the host details
  3. Click the Add Group button
  4. Fill in the required group name and optional fields
  5. Click Create to submit the request
  6. The group list will update automatically after creation

Group Creation Options

Option Description Platforms
group_name Name for the new group (required) All
gid Specific group ID number Unix/Linux/BSD/macOS
description Description or comment for the group Windows

Create via API

curl -X POST "https://your-server.example.com/api/v1/host/{host_id}/groups" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "group_name": "developers",
       "gid": 1001
     }'

Prerequisites

Privileged Mode Required

The SysManage agent must be running in privileged mode (as root or Administrator) to create user accounts and groups. If the agent is not running in privileged mode, the Add User and Add Group buttons will be disabled.

Checking Privileged Mode

The host detail page shows whether the agent is running in privileged mode. Look for the "Agent Privileged" indicator in the host information section.

Security Consideration

Running the agent in privileged mode grants it elevated system access. Only enable privileged mode on hosts where you need account management or other privileged operations.

Active Host Connection

The target host must be active and connected to the SysManage server. Account creation requests are queued and delivered to the agent when it's online.

Security and Access Control

Host account management operations are protected by role-based access control (RBAC). Users must have specific security roles to create accounts and groups.

Required Security Roles

  • ADD_HOST_ACCOUNT: Required to create user accounts on hosts
  • ADD_HOST_GROUP: Required to create groups on hosts
  • EDIT_HOST_ACCOUNT: Required to modify existing user accounts
  • EDIT_HOST_GROUP: Required to modify existing groups
  • DELETE_HOST_ACCOUNT: Required to delete user accounts
  • DELETE_HOST_GROUP: Required to delete groups

Assigning Host Account Roles

Administrators can assign host account management roles to users through the user management interface:

  1. Navigate to Administration > User Management
  2. Select the user to modify
  3. Click Edit Roles
  4. Select the appropriate host account management roles
  5. Save changes

Troubleshooting

Add User/Group Button Disabled

Symptoms: The Add User or Add Group button is grayed out

Solutions:

  • Verify the agent is running in privileged mode
  • Check that you have the required ADD_HOST_ACCOUNT or ADD_HOST_GROUP role
  • Ensure the host is active and connected

User/Group Creation Fails

Symptoms: Creation request returns an error

Solutions:

  • Check that the username/group name doesn't already exist
  • Verify the UID/GID isn't already in use
  • Review agent logs for detailed error messages
  • Ensure the specified shell exists on the target system

Permission Denied

Symptoms: "Permission denied" error message

Solutions:

  • Verify your user account has the required role (ADD_HOST_ACCOUNT or ADD_HOST_GROUP)
  • Contact administrator to request host account management permissions
  • Refresh your session after role changes

User/Group List Not Updating

Symptoms: Created user/group doesn't appear in the list

Solutions:

  • Wait a few moments for the agent to report updated data
  • Click "Request Host Data" to force an immediate update
  • Check WebSocket connection status in browser console

Best Practices

Naming Conventions

  • Use consistent username formats across your infrastructure
  • Follow your organization's naming standards for service accounts
  • Use descriptive group names that indicate purpose

Security Practices

  • Grant host account management roles only to trusted administrators
  • Review audit logs for account creation activities
  • Use separate service accounts for applications rather than shared accounts
  • Implement password policies for Windows accounts

Operational Practices

  • Create groups before creating users that need to belong to them
  • Document custom UID/GID assignments to avoid conflicts
  • Test account creation on non-production hosts first

Related Documentation

Quick Navigation

Host Management Monitoring