Table of Contents
🔧 User Management
addUser(args, callback)
Creates a new Linux user account.
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 argumentscallback - 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.
username (String) - Username to removecallback - Function(err)
linuxUser.removeUser("john", function(err) {
if (err) console.error(err);
else console.log('User removed');
});
getUsers(callback)
Retrieves information about all users.
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.
username (String) - Username to querycallback - 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.
username (String) - Username to querycallback - 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.
groupName (String) - Name of the group to createcallback - 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.
groupName (String) - Name of the group to removecallback - Function(err)
linuxUser.removeGroup("developers", function(err) {
if (err) console.error(err);
else console.log('Group removed');
});
getGroups(callback)
Retrieves information about all groups.
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.
groupName (String) - Name of the group to querycallback - 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.
username (String) - Username to addgroupName (String) - Group name to add user tocallback - 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.
username (String) - Username to set password forpassword (String) - New passwordcallback - 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.
key (String) - SSH public keycallback - 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.
user (String) - Usernamekey (String) - SSH public keycallback - 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.
username (String) - Username to querycallback - 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.
username (String) - Usernameargs (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 periodcallback - 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.
username (String) - Username to validateReturns: 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.
promisifyFunction (Function) - Optional custom promisify functionReturns: 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);
}
}