{"id":402,"date":"2025-02-05T07:20:52","date_gmt":"2025-02-05T07:20:52","guid":{"rendered":"https:\/\/www.aran.cat\/wp\/?p=402"},"modified":"2025-02-05T07:21:46","modified_gmt":"2025-02-05T07:21:46","slug":"configure-linux-debian-to-boot-into-a-fullscreen-application","status":"publish","type":"post","link":"https:\/\/www.aran.cat\/wp\/?p=402","title":{"rendered":"Configure linux debian to boot into a fullscreen application"},"content":{"rendered":"\n

Running kiosk-mode applications with confidence<\/p>\n\n\n\n

Configure linux debian to boot into a fullscreen application – Tech Couch<\/a><\/p>\n\n\n\n

Table of contents\n\nCreating a testing environment\nStarting an app in kiosk mode\nFine-tuning chromium for kiosk mode\nHandling power saving and blank screen\nUsing a splash screen during boot\nConfiguring virtual terminals\nPreventing users from escaping the kiosk app\nConsiderations for touchscreen devices\nDevice maintenance and security<\/code><\/pre>\n\n\n\n
<\/p>\n\n\n\n
Linux is often used to build so-called \u00abkiosk\u00bb systems; a configuration that will start a fullscreen application right after boot, without any user interaction or login required. This kind of configuration is common for DIY and low-cost devices, but is not as straight-forward as one may assume.<\/p>\n\n\n\n
Creating a testing environment<\/h2>\n\n\n\n
Since testing configurations on a physical device can be cumbersome, this article will use vagrant<\/a> and virtualbox<\/a> to create a virtual machine to test the configuration and see it in action. Make sure you have both tools installed, then write the following content into a file named Vagrantfile<\/code>:<\/p>\n\n\n\n
Vagrant.configure(\"2\") do |config|\n config.vm.box = \"debian\/bookworm64\"\n config.vm.provider \"virtualbox\" do |vb|\n   vb.gui = true\n   vb.cpus = 2\n   vb.memory = \"2048\"\n end\nend\n<\/pre>\n\n\n\n
You can now start your virtual machine with<\/p>\n\n\n\n
vagrant up\n<\/pre>\n\n\n\n
To interact with the virtual machine once it has been created, run<\/p>\n\n\n\n
vagrant ssh\n<\/pre>\n\n\n\n
to obtain an SSH session as the vagrant<\/code> user. This user is automatically created for you and already has sudo<\/code> privileges.<\/p>\n\n\n\n
When you are done testing, or want to start over, you can get rid of the virtual machine with<\/p>\n\n\n\n
vagrant destroy -f\n<\/pre>\n\n\n\n
To get a new clean virtual machine, simply use vagrant up<\/code> again.<\/p>\n\n\n\n
Starting an app in kiosk mode<\/h2>\n\n\n\n
The guide assumes you have a linux debian installation without any desktop environment installed (if you’re using the vagrant config above, you have exactly that).<\/em><\/p>\n\n\n\n
Before starting, make sure the packages are up to date<\/p>\n\n\n\n
sudo apt update -y && sudo apt upgrade -y\n<\/pre>\n\n\n\n
Next install the required packages:<\/p>\n\n\n\n
sudo apt install -y xserver-xorg x11-xserver-utils xinit matchbox-window-manager chromium\n<\/pre>\n\n\n\n
Here is a brief explanation of what we need each for:<\/p>\n\n\n\n
    \n
  • X server and tools (xserver-xorg<\/code>,\u00a0x11-xserver-utils<\/code>,\u00a0xinit<\/code>):\u00a0Handles the low-level basics for graphical applications, like displays, inputs and rendering.<\/em><\/li>\n<\/ul>\n\n\n\n
      \n
    • Window manager (matchbox-window-manager<\/code>):\u00a0Manages windows on top of xorg, including features like size, placement and responding to fullscreen requests. We chose this window manager specifically because it is extremely lightweight and works well for kiosk mode setups.<\/em><\/li>\n<\/ul>\n\n\n\n
        \n
      • Kiosk app (chromium<\/code>):\u00a0The application we want our system to boot into. Chromium is a simple browser that works well for displaying local or remote websites in kiosk mode, but you could use any other graphical application that has fullscreen support in it’s place.<\/em><\/li>\n<\/ul>\n\n\n\n
        <\/p>\n\n\n\n
        With these dependencies installed, it is time to configure the kiosk mode starting sequence. This requires a user that the system will automatically log in as, preferrably a newly created one for this specific purpose:<\/p>\n\n\n\n
        sudo useradd -m -s \/bin\/bash -p '' kioskuser\n<\/pre>\n\n\n\n
        This creates a new user called kioskuser<\/code>. They have a home created because we need to create init scripts there in a moment, use \/bin\/bash<\/code> as their shell because we need .bashrc<\/code> during startup, and have an empty password to allow passwordless login at boot.<\/p>\n\n\n\n
        The initial virtual terminal and login screen is handled by the getty service. In order to automatically log into our kiosk account at boot, we need to override the default parameters for it. Create the file \/etc\/systemd\/system\/getty@tty1.service.d\/override.conf<\/code> with adjusted ExecStart<\/code> parameters:<\/p>\n\n\n\n
        sudo mkdir \/etc\/systemd\/system\/getty@tty1.service.d\nsudo cat > \/etc\/systemd\/system\/getty@tty1.service.d\/override.conf<< EOF\n[Service]\nExecStart=\nExecStart=-\/sbin\/agetty --autologin kioskuser --noclear %I $TERM\nEOF\n<\/pre>\n\n\n\n
        Overriding the getty@tty1<\/code> service only applies our automatic login for the first virtual terminal tty1<\/code> (not others available through <\/em>ctrl<\/em><\/code>+<\/em>alt<\/em><\/code>+<\/em>f2<\/em><\/code>…<\/em>f6<\/em><\/code>, and not remote sessions like SSH)<\/em>. The first blank ExecStart=<\/code> line is intentional and important, as it clears the previous contents inherited from the main getty<\/code> service unit we are overriding. If it were missing, our arguments would be appended<\/em> to the original line, not working as intended. If you named your kiosk user differently, make sure to adjust the last line after the --autologin<\/code> flag to your custom username.<\/p>\n\n\n\n
        Now that the kioskuser<\/code> is automatically logged in as at boot, we can append a small script to the end of their .bashrc<\/code> file to start the xorg<\/code> display manager for the tty1<\/code> session (and not for subsequent sessions or remote connections)<\/em>:<\/p>\n\n\n\n
        sudo cat >> \/home\/kioskuser\/.bashrc<< EOF\nif [ -z \"\\$DISPLAY\" ] && [ \"\\$(tty)\" = \"\/dev\/tty1\" ]; then\n  startx\nfi\nEOF\n<\/pre>\n\n\n\n
        The last task is to start the window manager and kiosk application once the xorg server is ready. We can simply write those commands to a .xinitrc<\/code> file, which gets executed once the startx<\/code> command completes:<\/p>\n\n\n\n
        cat > \/home\/kioskuser\/.xinitrc<< EOF\nmatchbox-window-manager &\nchromium --kiosk https:\/\/tech-couch.com\nEOF\nsudo chown kioskuser:kioskuser \/home\/kioskuser\/.xinitrc\n<\/pre>\n\n\n\n
        Note the ampersand &<\/code> after the first command, ensuring the window manager starts in the background and does not block the chromium process.<\/p>\n\n\n\n
        Using the --kiosk<\/code> flag for chromium will automatically start it in fullscreen and disable some UI elements, like tabs and the search bar the top. Instead of a remote URL, you could also provide a filepath to a local HTML file.<\/p>\n\n\n\n
        All that is left to do now is reboot the machine to see the configuration take effect:<\/p>\n\n\n\n
        sudo reboot\n<\/pre>\n\n\n\n
        The virtual machine should now boot directly into the chromium application.<\/p>\n\n\n\n
        Fine-tuning chromium for kiosk mode<\/h2>\n\n\n\n
        While supplying the --kiosk<\/code> flag is a good start, there are other useful flags when running chromium in kiosk mode:<\/p>\n\n\n\n
          \n
        • --no-first-run<\/code>\u00a0suppresses the first-run dialog (asking to sign in \/ sync profiles)<\/li>\n<\/ul>\n\n\n\n
            \n
          • --incognito<\/code>\u00a0ensures browsing history, cookies and site data are not stored, since kiosk applications have to use for these features.<\/li>\n<\/ul>\n\n\n\n
              \n
            • --disable-restore-session-state<\/code>\u00a0prevents chromium from showing a \u00abrestore closed tabs\u00bb page after unexpected shutdown, like power loss. Since kiosk mode devices are often turned off by unplugging, this feature may interfere with normal operation.<\/li>\n<\/ul>\n\n\n\n
                \n
              • --disable-infobars<\/code>\u00a0hides infobars like the\u00a0\u00abChrome is being controlled by automated test software\u00bb<\/em>\u00a0message that might appear when instrumenting the browser with WebDriver or debugging tools<\/li>\n<\/ul>\n\n\n\n
                  \n
                • --disable-pinch<\/code>\u00a0disables pinch-to-zoom functionality for touchscreens.<\/li>\n<\/ul>\n\n\n\n
                  Depending on your use case, you may find some or all of these additional flags useful for chromium kiosk apps.<\/p>\n\n\n\n
                  Handling power saving and blank screen<\/h2>\n\n\n\n
                  If left in default configuration, the xorg display manager will turn off the screen after some time of inactivity to save power. This may me desirable for interactive devices that have a keyboard or touchscreen attached, as any form of input will wake up the system again. For passive devices like screens displaying advertisements or informational displays, this behavior is problematic and needs to be prevented.<\/p>\n\n\n\n
                  You can disable these features entirely by combining three xset<\/code> commands. Simply prepend these lines to the beginning<\/em> of \/home\/kioskuser\/.xinitrc<\/code>:<\/p>\n\n\n\n
                  xset s off\nxset -dpms\nxset s noblank\n<\/pre>\n\n\n\n
                  The first line prevents screen blanking, the second disables dpms (Display Power Management Signaling)<\/em> and the last one prevents any screen saver activation.<\/p>\n\n\n\n
                  Using a splash screen during boot<\/h2>\n\n\n\n
                  The default boot process is very noisy, printing numerous colored lines of logging output to the screen. For many devices running kiosk mode, this boot sequence may concern unsuspecting users, so hiding most of the noise is a good idea.<\/p>\n\n\n\n
                  This can be done by using a plymouth splash screen theme, which first needs to be installed:<\/p>\n\n\n\n
                  sudo apt install -y plymouth plymouth-themes plymouth-x11\n<\/pre>\n\n\n\n
                  Plymouth comes packaged with several themes by default, you can get a list of them with<\/p>\n\n\n\n
                  sudo plymouth-set-default-theme -l\n<\/pre>\n\n\n\n
                  Once you settled on a theme you want, apply it to your environment with<\/p>\n\n\n\n
                  sudo plymouth-set-default-theme -R tribar\n<\/pre>\n\n\n\n
                  The tribar<\/code> theme is a good default choice here, as it is lightweight enough to load fast but also clean and unintrusive.<\/p>\n\n\n\n
                  The second part to adjust for a cleaner boot experience is the grub configuration. Open \/etc\/default\/grub<\/code> and set GRUB_TIMEOUT=0<\/code> (create it if missing)<\/em>. Next, find the line GRUB_CMDLINE_LINUX_DEFAULT<\/code> and prepend<\/em> quiet loglevel=0 splash<\/code> to it.<\/p>\n\n\n\n
                  For example, if your grub<\/code> file looked like this initially:<\/p>\n\n\n\n
                  GRUB_DEFAULT=0\nGRUB_TIMEOUT=5\nGRUB_DISTRIBUTOR=`lsb_release -i -s 2> \/dev\/null || echo Debian`\nGRUB_CMDLINE_LINUX_DEFAULT=\"net.ifnames=0 biosdevname=0\"\nGRUB_CMDLINE_LINUX=\"consoleblank=0\"\n<\/pre>\n\n\n\n
                  it should look like this after modification:<\/p>\n\n\n\n
                  GRUB_DEFAULT=0\nGRUB_TIMEOUT=0\nGRUB_DISTRIBUTOR=`lsb_release -i -s 2> \/dev\/null || echo Debian`\nGRUB_CMDLINE_LINUX_DEFAULT=\" quiet loglevel=0 splash net.ifnames=0 biosdevname=0\"\nGRUB_CMDLINE_LINUX=\"consoleblank=0\"\n<\/pre>\n\n\n\n
                  Finally, run<\/p>\n\n\n\n
                  sudo upgrade-grub\n<\/pre>\n\n\n\n
                  to save your new configuration. The next reboot should be mostly quiet, with a splash screen or animation covering the remaining boot logging noise.<\/p>\n\n\n\n
                  If you want even more control over the boot animation, you could design your own plymouth theme or show a static image.<\/p>\n\n\n\n
                  Configuring virtual terminals<\/h2>\n\n\n\n
                  It is common for linux systems to dynamically provide several virtual terminals after boot. A virtual terminal is essentially a login session, just like the one we used to automatically log in. At any point in time, you may press ctrl<\/code>+alt<\/code>+f2<\/code> to switch to tty2<\/code> (the second virtual terminal)<\/em>, up to ctrl<\/code>+alt<\/code>+f6<\/code> for the last one.<\/p>\n\n\n\n
                  If you are following along with virtualbox, you need to use the software keyboard from the top menu under <\/em>input<\/em><\/code> > <\/em>Keyboard<\/em><\/code> > <\/em>Soft Keyboard ...<\/em><\/code> to send key combinations to the vm.<\/em><\/p>\n\n\n\n
                  Keeping this functionality may or may not be desirable: If end users can send inputs (e.g. a keyboard is connected to the device)<\/em>, they can effectively \u00abdisable\u00bb the device by switching to a different virtual console (where the kiosk app isn’t visible, and just a text-based login appears)<\/em>. Only users familiar with linux systems will recognize this and be able to amend it, while less experienced people have no choice but to restart the device.<\/p>\n\n\n\n
                  On the other hand, devices that cannot be interacted with directly like informational displays may want to keep this feature enabled to allow operators to quickly debug the device in-place, simply by attaching a keyboard to it and switching to another tty to log in and issue commands.<\/p>\n\n\n\n
                  If you want to disable virtual terminals and leave only the session used for the kiosk mode app, you need to find these lines in \/etc\/systemd\/logind.conf<\/code> and make sure they are not<\/em> commented out and have the correct values:<\/p>\n\n\n\n
                  NAutoVTs=1\nReserveVT=0\n<\/pre>\n\n\n\n
                  The first line defines how many total virtual terminals are automatically generated, the second defines a reserved login virtual terminal that is always available (where value <\/em>0<\/em><\/code> disables this feature)<\/em>.<\/p>\n\n\n\n
                  Your changes will take effect after the next reboot.<\/p>\n\n\n\n
                  Preventing users from escaping the kiosk app<\/h2>\n\n\n\n
                  Simply starting an app in fullscreen may initially look like everything works as intended, but as soon as users have access to input, they may be able to break out of the kiosk app. This can take many forms, for example alt<\/code>+f4<\/code> to close the kiosk app, ctrl<\/code>+tab<\/code> to try and switch to a different program or application-specific shortcuts like ctrl<\/code>+w<\/code> to close the current tab in chromium (thus closing the browser, since only one tab was open)<\/em>.<\/p>\n\n\n\n
                  The only reliable way to prevent these issues is to unbind all ctrl<\/code> and alt<\/code> keys (left and right)<\/em>, as this leaves their key combinations inaccessible. You can unbind them using xmodmap<\/code> when kioskuser<\/code> starts their xorg session by prepending this command to the beginning of \/home\/kioskuser\/.xinitrc<\/code>:<\/p>\n\n\n\n
                  xmodmap -e \"keycode 37 = NoSymbol\" \\\n        -e \"keycode 64 = NoSymbol\" \\\n        -e \"keycode 105 = NoSymbol\" \\\n        -e \"keycode 108 = NoSymbol\"\n<\/pre>\n\n\n\n
                  This solution has the added benefit that it only affects the kiosk app session on tty1<\/code>, other sessions (e.g. over SSH)<\/em> and other users remain unaffected.<\/p>\n\n\n\n
                  After a reboot, feel free to try all key combinations to ensure you cannot escape the kiosk environment with them anymore.<\/p>\n\n\n\n
                  If you are following along with virtualbox, you need to use the software keyboard from the top menu under <\/em>input<\/em><\/code> > <\/em>Keyboard<\/em><\/code> > <\/em>Soft Keyboard ...<\/em><\/code> to send key combinations to the vm.<\/em><\/p>\n\n\n\n
                  Considerations for touchscreen devices<\/h2>\n\n\n\n
                  Before adding touchscreen features to this setup, take a moment to consider if debian is the right platform for your needs. Handheld-optimized distributions like android will be significantly easier to set up for touch devices, and you are less likely to find edge-case issues or hardware incompatibilities with them.<\/p>\n\n\n\n
                  The primary need of a touchscreen device is a soft keyboard (an on-screen software keyboard)<\/em> to allow users to input keystrokes without a physical keyboard connected. There are many options here, from lightweight choices like matchbox-keyboard<\/code> (a good choice for the <\/em>matchbox-window-manager<\/em><\/code>)<\/em> to more complex and feature-rich alternatives like florence<\/code> or onboard<\/code>. The choice is mainly up to your device’s needs and personal preference, but be warned that setting up dynamic focus (automatically show\/hide the keyboard when text input is selected) may be tricky on some combinations.<\/p>\n\n\n\n
                  Since most touch devices do not show a cursor to the user, you likely want to hide the one on your touch device as well. An easy solution is to use unclutter<\/code> with an idle timeout of 0 seconds, to hide the cursor most of the time. This setup may cause a flickering cursor on mouse move for some touchscreens, in which case you need to use a more complex solution like creating and installing a cursor theme with an invisible cursor icon.<\/p>\n\n\n\n
                  Lastly, your kiosk application may behave unexpectedly with touch devices. The chromium browser for example, includes support for some touch gestures, like navigating with swiping motions or zooming with a pinch gesture. These can be easily disabled with flags --overscroll-history-navigation=0<\/code> and --disable-pinch<\/code>, respectively. Spend some time checking if and what touch gestures your application supports, and consider how that may negatively impact the user experience.<\/p>\n\n\n\n
                  Device maintenance and security<\/h2>\n\n\n\n
                  After setting up your device, you may think about how to maintain it in the future. Running an SSH server on the device to remotely manage it may seem like a good idea at first, but be careful to either disable SSH login for the kioskuser<\/code> account or limit logins to key-only authentication, as otherwise you provide remote access to anything in the device’s network through the passwordless kiosk application user.<\/p>\n\n\n\n
                  On the topic of security, you should make it a point to treat all your deployed\/installed devices as hostile. Even if no remote access is possible over SSH, an attacker could simply plug the storage disk into one of their machines and freely read\/change any files on the system. Do not store credentials on the device (like S3 storage bucket logins or FTP credentials), not even hardcoded into a compiled binary (strings can be stripped out of executables easily with the strings<\/code> command or debugging software).<\/p>\n\n\n\n
                  If your device needs authenticated access to remote infrastructure, for example to forward orders or reports, consider deploying a purpose-built REST API with limited access for the devices, and provide different API tokens for each device to easily lock specific ones out of the service should they start behaving undesirably or their token becomes compromised. Audit logging and rigid monitoring\/alerting are a valuable addition of such an API in production environments.<\/p>\n\n\n\n
                  <\/p>\n","protected":false},"excerpt":{"rendered":"
                  Running kiosk-mode applications with confidence Configure linux debian to boot into a fullscreen application – Tech Couch Linux is often used to build so-called \u00abkiosk\u00bb systems; a configuration that will start a fullscreen application right after boot, without any user interaction or login required. This kind of configuration is common […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[5,16,4],"tags":[],"class_list":["post-402","post","type-post","status-publish","format-standard","hentry","category-debian","category-informatica","category-programari-lliure"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/posts\/402","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=402"}],"version-history":[{"count":1,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/posts\/402\/revisions"}],"predecessor-version":[{"id":403,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=\/wp\/v2\/posts\/402\/revisions\/403"}],"wp:attachment":[{"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=402"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=402"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.aran.cat\/wp\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=402"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}