Users and Groups

Linux Users

Create Linux users in your VM with specific permissions and configurations:

import { freestyle } from "freestyle-sandboxes";

const { vm } = await freestyle.vms.create({
  users: [
    {
      name: "developer",
      uid: 1000,
      gecos: "Developer Account",
      groups: ["docker", "sudo"],
      home: "/home/developer",
      shell: "/bin/bash",
    },
    {
      name: "app",
      system: true, // System user (UID < 1000)
      home: "/var/app",
      shell: "/usr/sbin/nologin",
    },
  ],
});

User Properties

name (required) - Username
uid (optional) - Fixed user ID. If not provided, one is allocated automatically
gecos (optional) - Full name or description (e.g., "John Doe" or "Application User")
groups (optional) - Array of groups the user should belong to
home (optional) - Home directory path. Defaults:
- Regular users: /home/{username}
- System users: /
shell (optional) - Login shell. Defaults:
- Regular users: /bin/bash
- System users: /usr/sbin/nologin
system (optional) - If true, creates a system user (allocated from system UID range)

Linux Groups

Create Linux groups for organizing user permissions:

const { vm } = await freestyle.vms.create({
  groups: [
    {
      name: "developers",
      gid: 1001,
    },
    {
      name: "app-users",
      system: true, // System group (GID < 1000)
    },
  ],
  users: [
    {
      name: "alice",
      groups: ["developers", "docker"],
    },
    {
      name: "bob",
      groups: ["developers"],
    },
  ],
});

Group Properties

name (required) - Group name
gid (optional) - Fixed group ID. If not provided, one is allocated automatically
system (optional) - If true, creates a system group (allocated from system GID range)

Common Patterns

Web server with dedicated user

const { vm } = await freestyle.vms.create({
  groups: [
    { name: "www-data" },
  ],
  users: [
    {
      name: "webapp",
      groups: ["www-data"],
      home: "/var/www",
      shell: "/bin/bash",
    },
  ],
  systemd: {
    services: [
      {
        name: "web-server",
        mode: "service",
        exec: ["node server.js"],
        user: "webapp",
        group: "www-data",
        workdir: "/var/www",
      },
    ],
  },
});

Application user with restricted permissions

const { vm } = await freestyle.vms.create({
  groups: [
    { name: "appgroup", system: true },
  ],
  users: [
    {
      name: "appuser",
      system: true,
      groups: ["appgroup"],
      home: "/opt/app",
      shell: "/usr/sbin/nologin", // No interactive login
    },
  ],
  systemd: {
    services: [
      {
        name: "background-worker",
        mode: "service",
        exec: ["python worker.py"],
        user: "appuser",
        group: "appgroup",
        workdir: "/opt/app",
      },
    ],
  },
});

Shared file permissions

const { vm } = await freestyle.vms.create({
  groups: [
    { name: "shared", gid: 2000 },
  ],
  users: [
    {
      name: "user1",
      groups: ["shared"],
    },
    {
      name: "user2",
      groups: ["shared"],
    },
  ],
  additionalFiles: {
    "/shared/data.txt": {
      content: "Shared data",
    },
  },
});

// Set group ownership
await vm.exec("chgrp -R shared /shared");
await vm.exec("chmod -R g+w /shared");

User Management After Creation

You can also manage users after the VM is created:

// Add a new user
await vm.exec("useradd -m -s /bin/bash newuser");

// Add user to group
await vm.exec("usermod -aG docker newuser");

// Change user's shell
await vm.exec("chsh -s /bin/zsh newuser");

// Set password (if needed)
await vm.exec("echo 'newuser:password' | chpasswd");

// Create a new group
await vm.exec("groupadd mygroup");

Checking User and Group Information

// List all users
await vm.exec("cat /etc/passwd");

// List all groups
await vm.exec("cat /etc/group");

// Check current user
await vm.exec("whoami");

// Check user's groups
await vm.exec("groups username");

// Get detailed user info
await vm.exec("id username");

Best Practices

Use system users for services - Set system: true for application users to keep them separate from human users
Disable shell for service users - Use shell: "/usr/sbin/nologin" for users that only need to run services
Use groups for permissions - Create groups for shared access instead of adding individual permissions
Specify UIDs/GIDs for consistency - When working with shared storage or multiple VMs, use fixed UIDs/GIDs

Create users in templates - Put user configuration in templates for consistent caching:

const template = new VmTemplate({
  users: [
    { name: "webapp", system: true },
  ],
  groups: [
    { name: "www-data" },
  ],
});