API Reference

Complete documentation for linux-sys-user methods

🔧 User Management

addUser(args, callback)

Creates a new Linux user account.

Parameters:
args - Object or String. When a string is passed it is treated as { username: string, create_home: true }.
  • username (String) - User name of the user to be created
  • shell (String|null) - Path to login shell, null uses /usr/sbin/nologin
  • create_home (Boolean) - Create home directory
  • home_dir (String) - Custom home directory path
  • expiredate (String|Date) - Account expiration date
  • skel (String) - Skeleton directory for home
  • system (Boolean) - Create system account
  • selinux_user (String) - SELinux user
  • other_args (String|Array) - Additional arguments
callback - Function(err, userInfo)
// Example usage
linuxUser.addUser({
    username: "john",
    create_home: true,
    shell: "/bin/bash"
}, function(err, user) {
    if (err) console.error(err);
    else console.log('User created:', user);
});

// Using just username
linuxUser.addUser("john", function(err, user) {
    // Creates user with default settings
});

removeUser(username, callback)

Removes a user account and their home directory.

Parameters:
username (String) - Username to remove
callback - Function(err)
linuxUser.removeUser("john", function(err) {
    if (err) console.error(err);
    else console.log('User removed');
});

getUsers(callback)

Retrieves information about all users.

Parameters:
callback - Function(err, users)
linuxUser.getUsers(function(err, users) {
    if (err) console.error(err);
    else console.log('All users:', users);
});

getUserInfo(username, callback)

Retrieves information about a specific user.

Parameters:
username (String) - Username to query
callback - Function(err, userInfo)
linuxUser.getUserInfo("root", function(err, user) {
    if (err) console.error(err);
    else console.log('User info:', user);
});

getUserGroups(username, callback)

Retrieves all groups that a user belongs to.

Parameters:
username (String) - Username to query
callback - Function(err, groups)
linuxUser.getUserGroups("john", function(err, groups) {
    if (err) console.error(err);
    else console.log('User groups:', groups);
});

👥 Group Management

addGroup(groupName, callback)

Creates a new group.

Parameters:
groupName (String) - Name of the group to create
callback - Function(err, groupInfo)
linuxUser.addGroup("developers", function(err, group) {
    if (err) console.error(err);
    else console.log('Group created:', group);
});

removeGroup(groupName, callback)

Removes a group.

Parameters:
groupName (String) - Name of the group to remove
callback - Function(err)
linuxUser.removeGroup("developers", function(err) {
    if (err) console.error(err);
    else console.log('Group removed');
});

getGroups(callback)

Retrieves information about all groups.

Parameters:
callback - Function(err, groups)
linuxUser.getGroups(function(err, groups) {
    if (err) console.error(err);
    else console.log('All groups:', groups);
});

getGroupInfo(groupName, callback)

Retrieves information about a specific group.

Parameters:
groupName (String) - Name of the group to query
callback - Function(err, groupInfo)
linuxUser.getGroupInfo("developers", function(err, group) {
    if (err) console.error(err);
    else console.log('Group info:', group);
});

addUserToGroup(username, groupName, callback)

Adds a user to a group.

Parameters:
username (String) - Username to add
groupName (String) - Group name to add user to
callback - Function(err)
linuxUser.addUserToGroup("john", "developers", function(err) {
    if (err) console.error(err);
    else console.log('User added to group');
});

🔐 Password Management

setPassword(username, password, callback)

Sets or changes a user's password using chpasswd.

Parameters:
username (String) - Username to set password for
password (String) - New password
callback - Function(err)
linuxUser.setPassword("john", "newpassword123", function(err) {
    if (err) console.error(err);
    else console.log('Password set successfully');
});

🔑 SSH Key Management

verifySSHKey(key, callback)

Validates an SSH key format and extracts information.

Parameters:
key (String) - SSH public key
callback - Function(err, keyInfo)
const sshKey = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDBq...";
linuxUser.verifySSHKey(sshKey, function(err, info) {
    if (err) console.error('Invalid key:', err);
    else console.log('Key info:', info);
});

addSSHtoUser(user, key, callback)

Adds an SSH key to a user's authorized_keys file. If the key already exists, the call succeeds without creating a duplicate.

Parameters:
user (String) - Username
key (String) - SSH public key
callback - Function(err, success)
const sshKey = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDBq...";
linuxUser.addSSHtoUser("john", sshKey, function(err, success) {
    if (err) console.error(err);
    else console.log('SSH key added successfully');
});

⏰ Expiration Management

getExpiration(username, callback)

Retrieves user expiration and password policy information.

Parameters:
username (String) - Username to query
callback - Function(err, expirationInfo)
linuxUser.getExpiration("john", function(err, info) {
    if (err) console.error(err);
    else {
        console.log('Password last changed:', info.changed);
        console.log('Password expires:', info.passwordExpires);
        console.log('Account expires:', info.accountExpires);
        console.log('Min days between changes:', info.minDays);
        console.log('Max days validity:', info.maxDays);
        console.log('Warning days:', info.warnDays);
    }
});

setExpiration(username, args, callback)

Sets user expiration and password policy.

Parameters:
username (String) - Username
args (Object) - Expiration settings
  • lastday (Date|String) - Last password change
  • expiredate (Date|String) - Account expiration
  • inactive (Date|String) - Inactivity period
  • minDays (Number) - Min days between password changes
  • maxDays (Number) - Max password validity
  • warnDays (Number) - Warning period
callback - Function(err, data)
linuxUser.setExpiration("john", {
    maxDays: 90,
    warnDays: 7,
    inactive: 30
}, function(err) {
    if (err) console.error(err);
    else console.log('Expiration set successfully');
});

✅ Validation

validateUsername(username)

Validates whether a string is a valid Linux username.

Parameters:
username (String) - Username to validate
Returns: Boolean
if (linuxUser.validateUsername("john_doe")) {
    console.log('Valid username');
} else {
    console.log('Invalid username');
}

📦 Promise Support

.promise(promisifyFunction)

Returns a version of the API where all methods return Promises.

Parameters:
promisifyFunction (Function) - Optional custom promisify function
Returns: Object with all methods promisified
const linuxUser = require('linux-sys-user').promise();

// Using util.promisify (default)
const linuxUser = require('linux-sys-user').promise();

// Using custom promisify (e.g., Bluebird)
const bluebird = require('bluebird');
const linuxUser = require('linux-sys-user').promise(bluebird.promisify);

// Now all methods return promises
linuxUser.addUser({username: "john", create_home: true})
    .then(user => console.log('User created:', user))
    .catch(err => console.error('Error:', err));

// Or with async/await
async function createUser() {
    try {
        const user = await linuxUser.addUser({
            username: "john",
            create_home: true,
            shell: "/bin/bash"
        });
        console.log('User created:', user);
    } catch (err) {
        console.error('Error:', err);
    }
}