Quick Start Guide
This guide will help you get up and running with linux-sys-user in just a few minutes.
⚠️ Important: This module requires root privileges and must run on Linux. Most operations will fail if not running as root.
Prerequisites
- Linux operating system
- Node.js 6.0.0 or higher
- Root access (for most operations)
- Basic understanding of Linux user management
Step 1: Installation
Install the module using npm:
# Install from npm
npm install linux-sys-user --save
# Or install globally for command-line usage
npm install -g linux-sys-user
npm install linux-sys-user --save
# Or install globally for command-line usage
npm install -g linux-sys-user
Step 2: Basic Usage
Here's a simple example to get you started:
const linuxUser = require('linux-sys-user');
// Add a new user
linuxUser.addUser({
username: "john",
create_home: true,
shell: "/bin/bash"
}, function(err, user) {
if (err) {
return console.error('Error creating user:', err);
}
console.log('User created successfully:', user);
});
// Add a new user
linuxUser.addUser({
username: "john",
create_home: true,
shell: "/bin/bash"
}, function(err, user) {
if (err) {
return console.error('Error creating user:', err);
}
console.log('User created successfully:', user);
});
Step 3: Using Promises
For cleaner async/await code:
const linuxUser = require('linux-sys-user').promise();
// Using async/await
async function createUser() {
try {
const user = await linuxUser.addUser({
username: "jane",
create_home: true,
shell: "/bin/bash"
});
console.log('User created:', user);
} catch (err) {
console.error('Error:', err);
}
}
createUser();
// Using async/await
async function createUser() {
try {
const user = await linuxUser.addUser({
username: "jane",
create_home: true,
shell: "/bin/bash"
});
console.log('User created:', user);
} catch (err) {
console.error('Error:', err);
}
}
createUser();
Step 4: Common Operations
Here are some common operations you'll use frequently:
// Get all users
linuxUser.getUsers(function(err, users) {
console.log('All users:', users);
});
// Get specific user info
linuxUser.getUserInfo("root", function(err, user) {
console.log('Root user info:', user);
});
// Set a password
linuxUser.setPassword("john", "newpassword123", function(err) {
if (!err) console.log('Password set successfully');
});
// Add user to group
linuxUser.addUserToGroup("john", "developers", function(err) {
if (!err) console.log('User added to group');
});
linuxUser.getUsers(function(err, users) {
console.log('All users:', users);
});
// Get specific user info
linuxUser.getUserInfo("root", function(err, user) {
console.log('Root user info:', user);
});
// Set a password
linuxUser.setPassword("john", "newpassword123", function(err) {
if (!err) console.log('Password set successfully');
});
// Add user to group
linuxUser.addUserToGroup("john", "developers", function(err) {
if (!err) console.log('User added to group');
});
Step 5: Error Handling
Always handle errors properly:
function createUserSafely(username) {
// Validate username first
if (!linuxUser.validateUsername(username)) {
return console.error('Invalid username:', username);
}
linuxUser.addUser({
username: username,
create_home: true
}, function(err, user) {
if (err) {
// Handle specific error types
if (err.message.includes('Permission denied')) {
console.error('Must run as root');
} else if (err.message.includes('already exists')) {
console.error('User already exists');
} else {
console.error('Unknown error:', err);
}
} else {
console.log('User created successfully', user);
}
});
}
// Validate username first
if (!linuxUser.validateUsername(username)) {
return console.error('Invalid username:', username);
}
linuxUser.addUser({
username: username,
create_home: true
}, function(err, user) {
if (err) {
// Handle specific error types
if (err.message.includes('Permission denied')) {
console.error('Must run as root');
} else if (err.message.includes('already exists')) {
console.error('User already exists');
} else {
console.error('Unknown error:', err);
}
} else {
console.log('User created successfully', user);
}
});
}
💡 Pro Tips
- Always validate usernames using
validateUsername()before operations - Use promise version for cleaner async code
- Handle permission errors gracefully
- Test your code in a safe environment first
- Consider using system accounts for services
✅ Next Steps
Now that you have the basics down, explore:
- Complete API Reference - See all available methods
- Code Examples - Real-world usage patterns
- GitHub Repository - Source code and issues