System Requirements
⚠️ Important Prerequisites
Before installing linux-sys-user, ensure your system meets these requirements:
- Operating System: Linux (any distribution)
- Node.js: Version 6.0.0 or higher
- Privileges: Root access for most operations
- System Commands: useradd, userdel, groupadd, groupdel, usermod, passwd, chpasswd, chage, ssh-keygen
# Check your Node.js version node --version # Check if you're running as root whoami # Verify required commands are available which useradd userdel groupadd groupdel usermod passwd chpasswd chage ssh-keygen
Installation Methods
Method 1: npm (Recommended)
The easiest way to install linux-sys-user is using npm:
# Install as a dependency npm install linux-sys-user --save # Install globally (for CLI usage) npm install -g linux-sys-user # Install with specific version npm install linux-sys-user@1.2.0 --save
# Install as a dependency yarn add linux-sys-user # Install globally yarn global add linux-sys-user
# Install as a dependency pnpm add linux-sys-user # Install globally pnpm add -g linux-sys-user
Method 2: Manual Installation
For development or custom setups:
# Clone the repository git clone https://github.com/wmantly/linux-user.git cd linux-user # Install dependencies npm install # Link globally (optional) npm link
Method 3: Docker
Use in a containerized environment:
# Build from Dockerfile docker build -t linux-sys-user . # Run with privileges docker run --privileged -v /etc/passwd:/etc/passwd:ro -v /etc/group:/etc/group:ro linux-sys-user
Note: Docker usage requires careful consideration of security implications when dealing with system user management.
Setup & Configuration
Basic Setup
Start using linux-sys-user in your project:
// In your JavaScript/Node.js file
var linuxUser = require('linux-sys-user');
// Test the installation
linuxUser.getUsers(function (err, users) {
if (err) {
console.error('Error:', err);
} else {
console.log('Installation successful! Found', users.length, 'users');
}
});
Promise Support Setup
Enable promise-based API usage:
// Get promise-based API
var linuxUserPromise = require('linux-sys-user').promise();
// Use with async/await
async function example() {
try {
const users = await linuxUserPromise.getUsers();
console.log('Users:', users);
} catch (err) {
console.error('Error:', err);
}
}
TypeScript Support
TypeScript definitions are included automatically:
import LinuxUser, { UserInfo, UserCreationArgs } from 'linux-sys-user';
// TypeScript will provide autocompletion and type checking
const config: UserCreationArgs = {
username: "test_user",
create_home: true,
shell: "/bin/bash"
};
LinuxUser.addUser(config, (err, user: UserInfo | null) => {
if (err) {
console.error('Error:', err);
} else {
console.log('User created:', user);
}
});
Verification & Testing
Verify Installation
Test that everything is working correctly:
// test-installation.js
var linuxUser = require('linux-sys-user');
console.log('Testing linux-sys-user installation...\n');
// Test 1: Username validation
console.log('1. Testing username validation:');
console.log(' Valid username "test_user":', linuxUser.validateUsername('test_user'));
console.log(' Invalid username "$invalid":', linuxUser.validateUsername('$invalid'));
// Test 2: Get users (should work without root)
console.log('\n2. Testing getUsers:');
linuxUser.getUsers(function (err, users) {
if (err) {
console.log(' Error:', err.message);
} else {
console.log(' Success! Found', users.length, 'users');
console.log(' First user:', users[0].username);
}
});
// Test 3: Promise support
console.log('\n3. Testing promise support:');
var linuxUserPromise = require('linux-sys-user').promise();
linuxUserPromise.getUsers()
.then(users => console.log(' Promise test successful!'))
.catch(err => console.log(' Promise test error:', err.message));
console.log('\nInstallation test completed!');
# Run the test node test-installation.js
Run Official Tests
Run the project's test suite to ensure everything works:
# Run tests npm test # Run tests with coverage npm run test-coverage # Run linting npm run lint
Note: Some tests require root privileges and may fail if not run as root. This is expected behavior.
Troubleshooting
Common Issues
Permission Denied Errors
Issue: "Permission denied" when creating users
Solution: Run your script as root or with sudo
Solution: Run your script as root or with sudo
sudo node your-script.js
Command Not Found Errors
Issue: "useradd: command not found"
Solution: Install shadow-utils or passwd packages
Solution: Install shadow-utils or passwd packages
# Ubuntu/Debian sudo apt-get install shadow-utils # CentOS/RHEL/Fedora sudo yum install shadow-utils # or sudo dnf install shadow-utils
Module Not Found
Issue: "Cannot find module 'linux-sys-user'"
Solution: Reinstall the module
Solution: Reinstall the module
npm uninstall linux-sys-user npm install linux-sys-user --save
Platform Not Supported
Issue: "linux-user must be running on Linux"
Solution: This module only works on Linux systems
Solution: This module only works on Linux systems
Getting Help
Need help? Here are resources for getting support:
- Documentation: Check the API Reference and Examples
- GitHub Issues: Report bugs or request features
- Stack Overflow: Tag your question with 'linux-sys-user'
- GitHub Discussions: Join community discussions
Production Deployment
Security Considerations
Important Security Notes:
- Always validate user input before processing
- Use strong password policies
- Audit user creation and modification logs
- Implement proper error handling
- Consider using service accounts with minimal privileges
Environment Setup
# Production installation npm install --production --only=production # Environment variables export NODE_ENV=production export LINUX_USER_LOG_LEVEL=error # Process management pm2 start your-app.js --name "user-management-service"