Getting Started

Quick setup guide for linux-sys-user

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

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);
});

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();

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');
});

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);
    }
  });
}

💡 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: