linux-sys-user

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
sudo node your-script.js

Command Not Found Errors

Issue: "useradd: command not found"
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
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

Getting Help

Need help? Here are resources for getting support:

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"