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.
* **Chromium Kiosk:** Launches Chromium in full-screen kiosk mode.
* **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.
* **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.
* **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"`)
* `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_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
```
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
chmod +x setup-kiosk.sh
```
3. **Run as root:**
4. **Run as root:**
```bash
sudo ./setup-kiosk.sh
# or if already root:
# ./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. **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.
5. **Follow Prompts/Review Output:** The script will output its progress. Pay attention to any warnings, especially regarding `nomodeset` or WayVNC password settings.
6. **Reboot:**
```bash
@ -74,70 +76,68 @@ Before running the script, you can adjust the following variables at the top of
### 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).
* 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
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`
* **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:**
```bash
# Replace 'signage' if needed
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`)
* **Manually test Sway (on TTY2, after stopping greetd):**
```bash
# Stop greetd on TTY1
rc-service greetd stop
# Switch to TTY2 (Alt+F2), log in as signage user
# Then, as signage user:
rc-service greetd stop # Stop greetd on TTY1
# Switch to TTY2 (Alt+F2), log in as <SIGNAGE_USER>
dbus-run-session sway -d
```
### 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:
```bash
# Replace 'signage' if needed
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.
1. Edit the Sway configuration file: `vi /home/<SIGNAGE_USER>/.config/sway/config`
2. Find the `exec /usr/bin/chromium ...` line and remove or comment out `--disable-gpu`.
3. Save, then reload Sway (`Mod+Shift+c` or `swaymsg reload`) or reboot.
### 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
The script performs the following major steps:
1. **Root Check:** Ensures it's run as root.
2. **`nomodeset` Check:** Warns if `nomodeset` is active.
3. **Package Repositories:** Updates Alpine's package repositories.
4. **Wayland Base Setup:** Installs `alpine-conf` and runs `setup-wayland-base` (which enables community repo and installs `elogind`, `eudev`).
5. **Package Installation:** Installs Sway, Chromium, Mesa drivers, D-Bus, fonts, firmware, greetd, WayVNC, and open-vm-tools.
6. **D-Bus Service:** Enables and starts the D-Bus service.
7. **open-vm-tools Service:** Enables and starts the `open-vm-tools` service.
8. **Signage User Creation:** Creates the specified `SIGNAGE_USER`, their home directory, and adds them to `video` and `input` groups for necessary permissions.
9. **User Profile Configuration:** Creates a `~/.profile` for the signage user, mainly for setting the `WAYVNC_PASSWORD` environment variable.
10. **Sway Configuration:** Creates a Sway config file (`~/.config/sway/config`) that:
* Sets basic Sway options.
* Explicitly enables and powers on display outputs.
* Configures mouse cursor hiding.
* Autostarts Chromium in kiosk mode pointing to `KIOSK_URL`.
* Autostarts WayVNC.
* Sets minimal keybindings for debugging/control.
11. **Greetd Configuration:** Configures `greetd` (`/etc/greetd/config.toml`) to automatically log in the `SIGNAGE_USER` and launch Sway.
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.
14. **Final Information & Troubleshooting:** Prints a summary and troubleshooting tips.
1. **Root Check & Initial Info.**
2. **`nomodeset` Check.**
3. **Package Repositories Update.**
4. **Wayland Base Setup** (elogind, eudev).
5. **Package Installation:** Installs Sway, Chromium, greetd, WayVNC, etc. `openssl` is installed conditionally if TLS auth for WayVNC is enabled.
6. **D-Bus Service Setup.**
7. **open-vm-tools Service Setup.**
8. **Signage User Creation** (with `video` and `input` group membership).
9. **User Profile Configuration.**
10. **WayVNC Configuration:**
* If `WAYVNC_ENABLE_TLS_AUTH` is true: Generates self-signed TLS keys/certificates and creates `/home/<SIGNAGE_USER>/.config/wayvnc/config` with authentication enabled.
* If false: Skips WayVNC config file creation, ensuring WayVNC starts without its internal authentication.
11. **Sway Configuration:** Creates `~/.config/sway/config` to autostart Chromium and WayVNC (launch arguments for WayVNC depend on the auth setting).
12. **Greetd Configuration** for autologin.
13. **Inittab Configuration** to launch greetd on tty1.
14. **PAM Configuration** for elogind session management.
15. **Final Information & Troubleshooting.**
## License
This script is provided as-is. Feel free to use and modify it.