docs: Environment variables (#1254)

docs/environment.md

@@ -2,13 +2,15 @@
 
 This page lists all the environment variables that can be used to configure the container.
 
+An empty default means the variable is unset and its value is determined automatically when applicable.
+
 ## 💽 Virtual DSM
 
 | Variable | Default | Description |
 |---|---|---|
-| `URL` |  | URL or local path of the DSM `.pat` installation file. When unset, the default Virtual DSM image is downloaded automatically. |
+| `URL` |  | URL or local path to the DSM `.pat` installation file. Downloads the default Virtual DSM image automatically when unset. |
 | `HOST_MAC` |  | MAC address reported to DSM. |
-| `HOST_MODEL` |  | Synology host device model reported to DSM. |
+| `HOST_MODEL` |  | Synology host model reported to DSM. |
 | `HOST_SERIAL` |  | Synology host serial number reported to DSM. |
 | `GUEST_SERIAL` |  | Synology guest serial number reported to DSM. |
 
@@ -16,57 +18,57 @@ This page lists all the environment variables that can be used to configure the
 
 | Variable | Default | Description |
 |---|---|---|
-| `CPU_CORES` | `2` | Number of CPU cores assigned to the VM. Can also be set to `max` or `half`. |
+| `CPU_CORES` | `2` | Number of virtual CPU cores, such as `4`, `half`, or `max`. |
-| `CPU_MODEL` | `host` | QEMU CPU model to use. |
+| `CPU_MODEL` | `host` | QEMU CPU model. |
 | `CPU_FLAGS` |  | Additional QEMU CPU flags. |
-| `HOST_CPU` |  | CPU name reported to DSM. Automatically selected when unset. |
+| `HOST_CPU` |  | CPU name reported to DSM. Selected automatically when unset. |
-| `KVM` | `Y` | Enables KVM hardware acceleration. Set to `N` to disable. |
+| `KVM` | `Y` | Enables KVM hardware acceleration. |
-| `RAM_SIZE` | `2G` | Amount of RAM assigned to the VM, for example `2G`, `4G`, `max`, or `half`. |
+| `RAM_SIZE` | `2G` | Amount of RAM assigned to DSM, such as `2G`, `4G`, `half`, or `max`. |
-| `RAM_CHECK` | `Y` | Checks whether enough host memory is available before starting the VM. |
+| `RAM_CHECK` | `Y` | Checks whether enough host memory is available before starting DSM. |
 
 ## 💾 Storage
 
 | Variable | Default | Description |
 |---|---|---|
 | `DISK_SIZE` | `256G` | Size of the main data disk. |
-| `DISK_FMT` | `raw` | Disk image format, usually `raw` or `qcow2`. |
+| `DISK_FMT` | `raw` | Disk image format: `raw` or `qcow2`. |
-| `DISK_TYPE` | `scsi` | Disk controller/device type, such as `sata`, `scsi`, `nvme`, or `blk`. |
+| `DISK_TYPE` | `scsi` | Disk device type, such as `sata`, `scsi`, `nvme`, or `blk`. |
-| `DISK_CACHE` | `none` | QEMU disk cache mode, for example `none` or `writeback`. |
+| `DISK_CACHE` | `none` | Disk cache mode, such as `none` or `writeback`. |
-| `DISK_IO` | `native` | QEMU disk I/O mode, for example `native`, `threads`, or `io_uring`. |
+| `DISK_IO` | `native` | Disk I/O mode, such as `native`, `threads`, or `io_uring`. |
-| `DISK_DISCARD` | `unmap` | Enables TRIM/unmap support for the data disk. |
+| `DISK_DISCARD` | `unmap` | Discard/TRIM mode for the primary disk. |
-| `DISK_ROTATION` | `1` | Rotation rate reported to the guest. Use `1` for SSD-like storage. |
+| `DISK_ROTATION` | `1` | Rotation rate reported to the guest. Use `1` to identify the disk as an SSD. |
-| `DISK_FLAGS` |  | Additional options used when creating qcow2 disks. |
+| `DISK_FLAGS` |  | Additional options used when creating `qcow2` disks. |
-| `ALLOCATE` | `N` | Preallocates disk space when creating the data disk. |
+| `ALLOCATE` | `N` | Preallocates space for the data disks. |
-| `STORAGE` | `/storage` | Storage directory used for disks, firmware variables, and generated files. |
+| `STORAGE` | `/storage` | Storage directory used for disks, settings, and downloads. |
 
 ## 🌐 Networking
 
 | Variable | Default | Description |
 |---|---|---|
-| `NETWORK` | `Y` | Network mode. Common values are `Y` for NAT, `passt`, `slirp`, or `N` to disable networking. |
+| `NETWORK` |  | Network mode, such as `nat`, `passt`, `slirp`, or `N` to disable networking. |
-| `DHCP` | `N` | Enables DHCP/macvtap mode so the VM receives an address from the external LAN. |
+| `DHCP` | `N` | Enables macvtap networking so  DSM receives an address from the external LAN through DHCP. |
-| `IP` |  | Guest IP address override. |
+| `HOST` | `VirtualDSM` | Hostname assigned to DSM. |
+| `IP` |  | Overrides the automatically selected guest IPv4 address. |
 | `MAC` |  | Guest network adapter MAC address. |
-| `HOST` | `VirtualDSM` | Hostname assigned to the VM. |
-| `DEV` | `eth0` | Host/container network interface to use. |
-| `MTU` |  | Network MTU to use for the guest interface. |
-| `MASK` | `255.255.255.0` | IPv4 netmask. |
-| `TAP` | `dsm` | TAP/macvtap interface name. |
-| `BRIDGE` | `docker` | Bridge name used for NAT networking. |
 | `ADAPTER` | `virtio-net-pci` | QEMU network adapter model. |
-| `HOST_PORTS` |  | Ports reserved for services running on the host/container side. |
+| `DEV` | `eth0` | Container network interface used as the uplink. |
-| `USER_PORTS` |  | Additional ports to forward to the VM when using user-mode networking. |
+| `MTU` |  | MTU assigned to the guest network interface. |
-| `DNSMASQ_OPTS` |  | Additional dnsmasq options. |
+| `MASK` | `255.255.255.0` | IPv4 netmask. |
-| `DNSMASQ_DEBUG` | `N` | Enables dnsmasq log tailing. |
+| `TAP` | `dsm` | TAP or macvtap interface name. |
+| `BRIDGE` | `docker` | Bridge name used for NAT networking. |
+| `HOST_PORTS` |  | Ports excluded from guest forwarding. |
+| `USER_PORTS` |  | Additional ports to forward to DSM when using user-mode networking. |
+| `DNSMASQ_OPTS` |  | Additional options passed to dnsmasq. |
+| `DNSMASQ_DEBUG` | `N` | Enables dnsmasq debug output. |
 | `DNSMASQ_DISABLE` | `N` | Disables the internal dnsmasq resolver. |
-| `PASST_OPTS` |  | Additional passt options. |
+| `PASST_OPTS` |  | Additional options passed to passt. |
 | `PASST_DEBUG` | `N` | Enables passt debug output. |
 
 ## 🖥️ Display
 
 | Variable | Default | Description |
 |---|---|---|
-| `DISPLAY` | `none` | QEMU display backend. Common values are `vnc`, `disabled`, or `none`. |
+| `DISPLAY` | `none` | Display backend, such as `vnc`, `disabled`, or `none`. |
 | `VGA` | `none` | QEMU video adapter model. |
 | `GPU` | `N` | Enables Intel iGPU acceleration. |
 | `RENDERNODE` | `/dev/dri/renderD128` | Render node used for GPU acceleration. |
@@ -76,8 +78,8 @@ This page lists all the environment variables that can be used to configure the
 | Variable | Default | Description |
 |---|---|---|
 | `SHUTDOWN` | `Y` | Enables graceful shutdown. |
-| `TIMEOUT` | `115` | Timeout used while waiting for DSM to shut down. |
+| `TIMEOUT` | `115` | Maximum time, in seconds, to wait before forcing DSM to stop. |
-| `API_TIMEOUT` | `90` | Timeout used for the shutdown API call. |
+| `API_TIMEOUT` | `90` | Maximum time, in seconds, to wait for the shutdown API call. |
 
 ## 🐞 Debugging
 
@@ -87,5 +89,5 @@ This page lists all the environment variables that can be used to configure the
 | `TRACE` | `N` | Enables shell command tracing. |
 | `COM_PORT` | `2210` | Internal communication port used by the DSM host helper. |
 | `CHR_PORT` | `12345` | Internal character device port used by the DSM host helper. |
-| `HOST_DEBUG` | `N` | Enables debug output for the host helper. |
+| `HOST_DEBUG` | `N` | Enables debug output for the DSM host helper. |
-| `ARGUMENTS` |  | Additional raw QEMU arguments appended to the generated command line. |
+| `ARGUMENTS` |  | Additional raw arguments appended to the QEMU command line. |