# OS Base Role

Configures fundamental system settings for Debian-based systems including hostname, user accounts, SSH keys, package management, and sudo access.

## What it does

This role performs the following system configuration tasks:

- **System Identity**: Sets hostname, domain, and FQDN
- **User Management**: Creates system and regular users with specified UIDs, groups, and home directories
- **SSH Access**: Deploys authorized SSH keys for users
- **Package Management**: Configures APT preferences and installs base packages
- **Sudo Configuration**: Sets up wheel group with passwordless sudo access
- **Security Groups**: Ensures wheel and sudo groups exist

## Variables

### Required Variables

| Variable | Type | Description | Default |
|----------|------|-------------|---------|
| `system_accounts` | list | List of user accounts to create | `[]` |
| `system_packages` | list | List of packages to install | `[]` |

### Optional Variables

| Variable | Type | Description | Default |
|----------|------|-------------|---------|
| `system_hostname` | string | System hostname | `inventory_hostname` first part |
| `system_domain` | string | System domain name | `inventory_hostname` remaining parts |
| `system_fqdn` | string | Full qualified domain name | `system_hostname.system_domain` |
| `system_packages_norecommend` | bool | Disable APT recommended packages | `false` |
| `system_packages_nosuggest` | bool | Disable APT suggested packages | `false` |

### System Account Configuration

Each account in `system_accounts` supports these properties:

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| `name` | string | Username (required) | - |
| `state` | string | User state: present/absent | `present` |
| `system` | bool | Create as system user | `false` |
| `uid` | int | User ID | auto-assigned |
| `groups` | list | User groups | `[]` |
| `comment` | string | User description | - |
| `shell` | string | Login shell | `/bin/bash` |
| `home` | string | Home directory | `/home/{{ name }}` |
| `create_home` | bool | Create home directory | `true` |
| `sshkey_state` | string | SSH key state: present/absent | `present` |
| `sshkeys` | list | List of SSH public keys | `[]` |
| `permissions` | list | Special permissions | `[]` |

### Supported Permissions

- `sudo`: Add user to sudo group (password required)
- `sudo_nopass`: Add user to wheel group (passwordless sudo)
- `libvirt`: Add user to libvirt group

## Examples

### Basic Configuration

```yaml
system_accounts:
  - name: admin
    uid: 1000
    groups: [sudo, wheel]
    comment: "System Administrator"
    sshkeys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@workstation

system_packages:
  - htop
  - vim
  - git
  - curl
```

### Advanced User Setup

```yaml
system_accounts:
  - name: sysmaint
    state: present
    system: true
    uid: 1000
    groups: [sudo, wheel]
    comment: "Maintenance user"
    sshkey_state: present
    sshkeys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... maint@jumpbox
    permissions: &maint_permissions
      - sudo
      - sudo_nopass
      - libvirt

  - name: john
    uid: 1001
    groups: [sudo, wheel]
    comment: "Primary admin"
    sshkeys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... john@laptop
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... john@desktop
    permissions: *maint_permissions

system_packages:
  - htop
  - vim
  - ncdu
  - git
  - iftop
  - rsync
  - bash

system_packages_norecommend: true
system_packages_nosuggest: true
```

### Custom Hostname Configuration

```yaml
system_hostname: "webserver"
system_domain: "example.com"
system_fqdn: "webserver.example.com"

system_accounts:
  - name: webadmin
    uid: 1000
    groups: [sudo]
    comment: "Web server administrator"
    sshkeys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... webadmin@deploy

system_packages:
  - nginx
  - certbot
  - fail2ban
```