rc/fri-alpine-signage
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.md to enhance WayVNC configuration details, clarify TLS authentication options, and improve user guidance on password security.

Browse source
This commit is contained in:
FallingLights 2025-05-07 20:38:46 +02:00
parent d39e11b722
commit 4e4ba096b4
1 changed files with 57 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
README.md
View file

@ -8,9 +8,11 @@ This script automates the setup of a minimal, Wayland-based kiosk on Alpine Linu
* **Wayland Native:** Uses Sway for a modern display server environment. * **Wayland Native:** Uses Sway for a modern display server environment.
* **Chromium Kiosk:** Launches Chromium in full-screen kiosk mode. * **Chromium Kiosk:** Launches Chromium in full-screen kiosk mode.
* **Autologin:** Uses `greetd` with `agreety` to automatically log in the signage user and start Sway. * **Autologin:** Uses `greetd` with `agreety` to automatically log in the signage user and start Sway.
* **Remote Access:** Includes WayVNC for remote desktop access to the kiosk session (password configuration required for security). * **Configurable Remote Access (WayVNC):**
* **TLS Authenticated:** Option to enable username/password authentication for WayVNC, secured with self-signed TLS certificates generated by the script.
* **Passwordless:** Option for passwordless VNC access (use with caution on trusted networks or with SSH tunneling).
* **VM Friendly:** Includes `open-vm-tools` for better integration when run in VMware. * **VM Friendly:** Includes `open-vm-tools` for better integration when run in VMware.
* **Customizable:** Key settings like the KIOSK URL, signage user, and WayVNC password can be configured. * **Customizable:** Key settings like KIOSK URL, signage user, and WayVNC options can be configured.
* **Dynamic Step Logging:** Script output clearly indicates progress with dynamic step numbering. * **Dynamic Step Logging:** Script output clearly indicates progress with dynamic step numbering.
* **Colorized Output:** Script output uses colors for better readability. * **Colorized Output:** Script output uses colors for better readability.
@ -26,7 +28,17 @@ Before running the script, you can adjust the following variables at the top of
* `KIOSK_URL`: The URL that Chromium will display. (Default: `"https://example.com"`) * `KIOSK_URL`: The URL that Chromium will display. (Default: `"https://example.com"`)
* `SIGNAGE_USER`: The dedicated user account for the kiosk. (Default: `"signage"`) * `SIGNAGE_USER`: The dedicated user account for the kiosk. (Default: `"signage"`)
* `WAYVNC_PASSWORD_TO_SET`: **Leave this blank in the script for better security.** The script will remind you to set it manually in the user's `~/.profile` after setup. If you *must* pre-set it, ensure it's a strong password.
### WayVNC Configuration:
* `WAYVNC_ENABLE_TLS_AUTH`:
* Set to `true` (default) to enable username/password authentication for WayVNC. This will also generate self-signed TLS certificates for encryption. `openssl` package will be installed.
* Set to `false` for passwordless VNC access. WayVNC will start without requiring authentication.
* `WAYVNC_PASSWORD_TO_SET`:
* Used only if `WAYVNC_ENABLE_TLS_AUTH` is `true`.
* Set a strong password here. (Default: `"burek123"` - **CHANGE THIS!**)
* If left blank and TLS auth is enabled, the script will use an **INSECURE default password "changeme"** and issue a critical warning.
* `WAYVNC_USERNAME`: The username for VNC authentication if `WAYVNC_ENABLE_TLS_AUTH` is `true`. (Default: `"signage_vnc"`)
* `WAYVNC_LISTEN_ADDRESS`: The IP address WayVNC listens on. (Default: `"0.0.0.0"` for all interfaces) * `WAYVNC_LISTEN_ADDRESS`: The IP address WayVNC listens on. (Default: `"0.0.0.0"` for all interfaces)
* `WAYVNC_PORT`: The port WayVNC listens on. (Default: `"5900"`) * `WAYVNC_PORT`: The port WayVNC listens on. (Default: `"5900"`)
@ -38,31 +50,21 @@ Before running the script, you can adjust the following variables at the top of
# or copy the script content into a file named setup-kiosk.sh # or copy the script content into a file named setup-kiosk.sh
``` ```
2. **Make it executable:** 2. **Review and Edit Configuration:** Open `setup-kiosk.sh` and adjust the configuration variables, especially WayVNC settings, to your needs. **Ensure you set a strong `WAYVNC_PASSWORD_TO_SET` if `WAYVNC_ENABLE_TLS_AUTH` is `true`.**
3. **Make it executable:**
```bash ```bash
chmod +x setup-kiosk.sh chmod +x setup-kiosk.sh
``` ```
3. **Run as root:** 4. **Run as root:**
```bash ```bash
sudo ./setup-kiosk.sh sudo ./setup-kiosk.sh
# or if already root: # or if already root:
# ./setup-kiosk.sh # ./setup-kiosk.sh
``` ```
4. **Follow Prompts/Review Output:** The script will output its progress. Pay attention to any warnings, especially regarding `nomodeset` or WayVNC password. 5. **Follow Prompts/Review Output:** The script will output its progress. Pay attention to any warnings, especially regarding `nomodeset` or WayVNC password settings.
5. **Change WayVNC Password:**
Edit the signage user's profile:
```bash
# Replace 'signage' if you changed SIGNAGE_USER
vi /home/signage/.profile
```
Uncomment and set the `WAYVNC_PASSWORD` variable:
```profile
export WAYVNC_PASSWORD="your_very_secure_password_here"
```
Save the file.
6. **Reboot:** 6. **Reboot:**
```bash ```bash
@ -74,70 +76,68 @@ Before running the script, you can adjust the following variables at the top of
### Remote Access (VNC) ### Remote Access (VNC)
* **If `WAYVNC_ENABLE_TLS_AUTH` was `true`:**
* Connect to the kiosk using a VNC client to the IP address of your Alpine Linux machine on the port specified by `WAYVNC_PORT` (default 5900). * Connect to the kiosk using a VNC client to the IP address of your Alpine Linux machine on the port specified by `WAYVNC_PORT` (default 5900).
* You will be prompted for the `WAYVNC_PASSWORD` you set in `/home/<SIGNAGE_USER>/.profile`. * You will be prompted for the `WAYVNC_USERNAME` and `WAYVNC_PASSWORD_TO_SET` configured in the script.
* Your VNC client will likely warn about an untrusted certificate because it's self-signed by the script. You will need to review and accept this certificate to proceed.
* **If `WAYVNC_ENABLE_TLS_AUTH` was `false`:**
* Connect to the kiosk using a VNC client to the IP address and port. No password will be required.
* **SECURITY WARNING:** This mode is insecure. It's highly recommended to restrict network access to the VNC port (e.g., using a firewall) or access it exclusively via an SSH tunnel.
### Troubleshooting ### Troubleshooting
The script provides a list of troubleshooting steps at the end of its execution. Key logs and checks include: The script provides a list of troubleshooting steps at the end of its execution. Key logs and checks include:
* **Greetd logs:** `grep greetd /var/log/messages | tail -n 20` * **Greetd logs:** `grep greetd /var/log/messages | tail -n 20`
* **Sway log:** `cat /home/<SIGNAGE_USER>/.local/share/sway/sway-greetd.log` (replace `<SIGNAGE_USER>` with your chosen user) * **Sway log:** `cat /home/<SIGNAGE_USER>/.local/share/sway/sway-greetd.log`
* **Sway config syntax check:** * **Sway config syntax check:**
```bash ```bash
# Replace 'signage' if needed # Replace 'signage' if needed
su - signage -c "export XDG_RUNTIME_DIR=/run/user/$(id -u signage) && sway -C -c /home/signage/.config/sway/config" su - signage -c "export XDG_RUNTIME_DIR=/run/user/$(id -u signage) && sway -C -c /home/signage/.config/sway/config"
``` ```
* **WayVNC Configuration (if TLS auth enabled):** `cat /home/<SIGNAGE_USER>/.config/wayvnc/config`
* **Required user groups:** `groups <SIGNAGE_USER>` (should include `video` and `input`) * **Required user groups:** `groups <SIGNAGE_USER>` (should include `video` and `input`)
* **Manually test Sway (on TTY2, after stopping greetd):** * **Manually test Sway (on TTY2, after stopping greetd):**
```bash ```bash
# Stop greetd on TTY1 rc-service greetd stop # Stop greetd on TTY1
rc-service greetd stop # Switch to TTY2 (Alt+F2), log in as <SIGNAGE_USER>
# Switch to TTY2 (Alt+F2), log in as signage user
# Then, as signage user:
dbus-run-session sway -d dbus-run-session sway -d
``` ```
### Modifying Chromium Flags ### Modifying Chromium Flags
Chromium is launched with `--disable-gpu` by default for compatibility, especially in VMs. If you have working 3D acceleration and want to try enabling GPU acceleration for potentially better performance: Chromium is launched with `--disable-gpu` by default for compatibility. To try enabling GPU acceleration:
1. Edit the Sway configuration file: 1. Edit the Sway configuration file: `vi /home/<SIGNAGE_USER>/.config/sway/config`
```bash 2. Find the `exec /usr/bin/chromium ...` line and remove or comment out `--disable-gpu`.
# Replace 'signage' if needed 3. Save, then reload Sway (`Mod+Shift+c` or `swaymsg reload`) or reboot.
vi /home/signage/.config/sway/config
```
2. Find the `exec /usr/bin/chromium ...` line.
3. Remove or comment out the `--disable-gpu` flag.
4. You might also want to remove `--ignore-gpu-blocklist`.
5. Save the file.
6. You can reload Sway without rebooting (if you can access a terminal or via VNC): `swaymsg reload` or by pressing `Mod+Shift+c` (if you kept the default keybinding). Otherwise, reboot.
### Kernel Parameter `nomodeset` ### Kernel Parameter `nomodeset`
If the script warns about `nomodeset` being present in your kernel command line (`/proc/cmdline`), Wayland (and thus Sway) will **not** function correctly. You **must** remove this parameter from your bootloader configuration (e.g., `/etc/default/grub` for GRUB, or `/boot/extlinux.conf` for syslinux/extlinux) and update your bootloader, then reboot. If the script warns about `nomodeset`, Wayland (and Sway) will **not** function correctly. Remove this parameter from your bootloader configuration (e.g., `/etc/default/grub` or `/boot/extlinux.conf`), update your bootloader, and reboot.
## Script Breakdown ## Script Breakdown
The script performs the following major steps: The script performs the following major steps:
1. **Root Check:** Ensures it's run as root. 1. **Root Check & Initial Info.**
2. **`nomodeset` Check:** Warns if `nomodeset` is active. 2. **`nomodeset` Check.**
3. **Package Repositories:** Updates Alpine's package repositories. 3. **Package Repositories Update.**
4. **Wayland Base Setup:** Installs `alpine-conf` and runs `setup-wayland-base` (which enables community repo and installs `elogind`, `eudev`). 4. **Wayland Base Setup** (elogind, eudev).
5. **Package Installation:** Installs Sway, Chromium, Mesa drivers, D-Bus, fonts, firmware, greetd, WayVNC, and open-vm-tools. 5. **Package Installation:** Installs Sway, Chromium, greetd, WayVNC, etc. `openssl` is installed conditionally if TLS auth for WayVNC is enabled.
6. **D-Bus Service:** Enables and starts the D-Bus service. 6. **D-Bus Service Setup.**
7. **open-vm-tools Service:** Enables and starts the `open-vm-tools` service. 7. **open-vm-tools Service Setup.**
8. **Signage User Creation:** Creates the specified `SIGNAGE_USER`, their home directory, and adds them to `video` and `input` groups for necessary permissions. 8. **Signage User Creation** (with `video` and `input` group membership).
9. **User Profile Configuration:** Creates a `~/.profile` for the signage user, mainly for setting the `WAYVNC_PASSWORD` environment variable. 9. **User Profile Configuration.**
10. **Sway Configuration:** Creates a Sway config file (`~/.config/sway/config`) that: 10. **WayVNC Configuration:**
* Sets basic Sway options. * If `WAYVNC_ENABLE_TLS_AUTH` is true: Generates self-signed TLS keys/certificates and creates `/home/<SIGNAGE_USER>/.config/wayvnc/config` with authentication enabled.
* Explicitly enables and powers on display outputs. * If false: Skips WayVNC config file creation, ensuring WayVNC starts without its internal authentication.
* Configures mouse cursor hiding. 11. **Sway Configuration:** Creates `~/.config/sway/config` to autostart Chromium and WayVNC (launch arguments for WayVNC depend on the auth setting).
* Autostarts Chromium in kiosk mode pointing to `KIOSK_URL`. 12. **Greetd Configuration** for autologin.
* Autostarts WayVNC. 13. **Inittab Configuration** to launch greetd on tty1.
* Sets minimal keybindings for debugging/control. 14. **PAM Configuration** for elogind session management.
11. **Greetd Configuration:** Configures `greetd` (`/etc/greetd/config.toml`) to automatically log in the `SIGNAGE_USER` and launch Sway. 15. **Final Information & Troubleshooting.**
12. **Inittab Configuration:** Modifies `/etc/inittab` to start `greetd` on `tty1` instead of a regular login getty.
13. **PAM Configuration:** Attempts to add `pam_elogind.so` to the PAM stack for proper session management with elogind. ## License
14. **Final Information & Troubleshooting:** Prints a summary and troubleshooting tips.
This script is provided as-is. Feel free to use and modify it.