From 43039e19f7f4b0622028a9c72d288e155573aac0 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Tue, 29 May 2018 18:12:27 +0200 Subject: [PATCH] sculpt: update documentation to Sculpt TC --- repos/gems/recipes/pkg/sculpt/README | 746 ++++++++++----------------- 1 file changed, 279 insertions(+), 467 deletions(-) diff --git a/repos/gems/recipes/pkg/sculpt/README b/repos/gems/recipes/pkg/sculpt/README index adea8649ad..0b43c7032a 100644 --- a/repos/gems/recipes/pkg/sculpt/README +++ b/repos/gems/recipes/pkg/sculpt/README @@ -1,8 +1,8 @@ - ============================== - Sculpt for Early Adopters (EA) - ============================== + =========================== + Sculpt for The Curious (TC) + =========================== Norman Feske @@ -23,10 +23,9 @@ Sculpt system will cover the following topics: * A boot image that is a live system, rescue system, and bootstrap system all in one, * Ways to tweak and introspect the system, -* Formatting a SATA disk and storing files on the file system, -* Connecting to a wireless network and downloading content from the internet, -* Installation of additional software, -* Deployment of the installed software, and +* Formatting a hard disk or USB stick and storing files on the file system, +* Connecting to a wired or wireless network, +* Installing and deploying software, and * Running a guest operating system inside a virtual machine. @@ -48,17 +47,18 @@ Your feedback is appreciated! [https://www.genode-labs.com] A printable PDF version of this document is available at -[https://genode.org/documentation/sculpt-ea.pdf]. +[https://genode.org/documentation/sculpt-tc.pdf]. Prerequisites ############# -Sculpt for Early Adopters (EA) is the first of a series of revisions with a -successively increased ease of use, which is actually just a subtle way of -admitting that it is currently rather difficult to use. +Sculpt for The Curious (TC) is the second of four revisions planned for 2018 +with a successively increased ease of use. In constrast to the initial version, +it introduces a graphical user interface for performing fundamental tasks like +connecting to a wireless network. -Sculpt EA expects that you already know your way around Genode's source tree +Sculpt TC expects that you already know your way around Genode's source tree and tool chain. Should this not be the case, please consider the "Getting started" section of the Genode Foundations book that is available as a free download at [https://genode.org]. @@ -67,9 +67,9 @@ download at [https://genode.org]. Vim skills required =================== -Sculpt EA leverages (a subset of) GNU coreutils, bash, and Vim as the user +Sculpt TC leverages (a subset of) GNU coreutils, bash, and Vim as the user interface for sculpting the system. If you are not yet familiar with using -Vim, you may take Sculpt EA as a welcome chance to get your toes wet. To +Vim, you may take Sculpt TC as a welcome chance to get your toes wet. To enjoy the experience, you should be comfortable with the following operations: @@ -88,7 +88,7 @@ operations: Hardware requirements and preparations ====================================== -Sculpt EA should be compatible with recent Intel-based PC hardware +Sculpt TC should be compatible with recent Intel-based PC hardware featuring Intel graphics, E1000 networking, Intel wireless, and AHCI. It is tested best on laptops of the Lenovo X and T series (X220, X250, @@ -97,11 +97,9 @@ refurbished version of one of these. You may also find the unofficial hardware compatibility list [http://usr.sysret.de/jws/genode/hcl.html] helpful for finding Genode-compatible hardware. -The machine is expected to have a single SATA disk drive attached to an -AHCI controller. NVMe is not supported. The content of the disk will be -wiped in the process of following this guide. Sculpt has been tested with -screen resolutions up to 2560 x 1440. Displays with a higher resolution -are not expected to work. The sweet spot is a full-HD display. +Sculpt has been tested with screen resolutions up to 2560 x 1440. Displays +with a higher resolution are not expected to work. The sweet spot is a full-HD +display. Please revisit the BIOS settings of your machine in the following respects: @@ -111,10 +109,15 @@ Please revisit the BIOS settings of your machine in the following respects: :VT-x enabled: Hardware-assisted virtualization is needed to run VirtualBox on top of Sculpt. -:Boot from USB enabled: Sculpt is booted from a USB stick. +:Boot from USB enabled: Sculpt is usually booted from a USB stick. -:Legacy boot enabled (recommended): Needed to boot from USB in legacy BIOS - mode, which is the default when building the Sculpt boot image. +:UEFI boot enabled: Sculpt TC boots via UEFI by default. The boot image + is specially prepared such that it can be started via legacy boot on older + machines. However, booting it via legacy boot on a modern machine is + hit or miss. + +:UEFI secure boot disabled: The Sculpt TC boot image is not cryptographically + signed. :Optimize for performance when battery powered: If the latter is not set, the hardware may behave erratically (e.g., non-working trackpoint when on @@ -131,18 +134,18 @@ GNU/Linux system. For reference, Ubuntu 16.04 is known to work well. ! git clone https://github.com/genodelabs/genode.git ! cd genode - ! git checkout 18.02 + ! git checkout 18.05 # Download the support for the NOVA microkernel - ! ./tool/depot/download genodelabs/bin/x86_64/base-nova/2018-02-26 + ! ./tool/depot/download genodelabs/bin/x86_64/base-nova/2018-05-30 The content is downloaded to the _public/_ directory and extracted to the _depot/_ directory. # Download all ingredients for the Sculpt boot image - ! ./tool/depot/download genodelabs/pkg/x86_64/sculpt/2018-02-27 + ! ./tool/depot/download genodelabs/pkg/x86_64/sculpt/2018-05-31 # Create a build directory @@ -150,19 +153,22 @@ GNU/Linux system. For reference, Ubuntu 16.04 is known to work well. # Configure the build directory by editing _build/x86_64/etc/build.conf_. Most importantly, enable the 'gems' source-code repository where the - sculpt scenario resides. In addition the 'ports', 'dde_linux' and 'dde_ipxe' - repository are needed as well. + Sculpt scenario resides. In addition, the 'ports', 'dde_linux' and 'dde_ipxe' + repository are needed as well. Second, change the default configuration + of the 'QEMU_RUN_OPT' variable to 'image/disk' instead of 'image/iso'. + This way, the build process will produce a valid disk image with a GPT + partition table instead of a legacy ISO image. -# Create the sculpt boot image (defined by the run script at +# Create the Sculpt boot image (defined by the run script at _repos/gems/run/sculpt.run_) ! make -C build/x86_64 run/sculpt KERNEL=nova - The boot image is created at _build/x86_64/var/run/sculpt.iso_. + The boot image is created at _build/x86_64/var/run/sculpt.img_. # Write the boot image to a USB stick: - ! sudo dd if=build/x86_64/var/run/sculpt.iso of=/dev/sdx bs=1M conv=fsync + ! sudo dd if=build/x86_64/var/run/sculpt.img of=/dev/sdx bs=1M conv=fsync Here, '/dev/sdx' refers to the device node of your USB stick. To determine it, you may inspect the output of 'dmesg' after plugging it in. @@ -171,7 +177,7 @@ GNU/Linux system. For reference, Ubuntu 16.04 is known to work well. Base system ########### -Unless customized, the sculpt base system resides as a self-contained live +Unless customized, the Sculpt base system resides as a self-contained live operating system on a USB stick, not installed on disk. This has two advantages. First, it makes the update of the base system straight-forward and completely risk-free. Simply install the new version on a second USB @@ -198,14 +204,14 @@ System overview [image sculpt_overview] System overview -The sculpt system consists of four parts living on top of the microkernel +The Sculpt system consists of four parts living on top of the microkernel (Figure [sculpt_overview]). Static system ------------- -The first - static - part of the system is baked-in the boot image. It +The first - static - part of the system is baked into the boot image. It contains components that must be shared by the upper - dynamic - parts and defines the relationships between the upper parts via a static policy that is fixed by the creator of the boot image. @@ -291,27 +297,31 @@ render your system temporarily inaccessible, eventually requiring a reboot. But don't be afraid. Since all manual changes performed in the Leitzentrale occur in memory only, you are not at risk of permanently bricking your machine. +The Leitzentrale can be toggled at any time by pressing F12 and will be enabled +right after boot. It presents itself with a minimalistic GUI for accessing +the storage devices attached to your machine and for configuring your network +connectivity. Most importantly, however, it allows the user to spawn an +interactive shell for manual _config_ and _report_ file +systems access. To spawn this command-line interface, click on the "ram" item from +the menu and select "Inspect". + [image noux 45%] Noux runtime environment for executing Unix tools -The Leitzentrale can be toggled at any time by pressing F12 and will be enabled -right after boot. It uses a small Unix runtime called noux (Figure [noux]) +The inspect window hosts a small Unix runtime called noux (Figure [noux]) as user interface. Don't let the presence of a Unix shell mislead you. Sculpt is not a Unix system. It merely uses Unix subsystems in the form of noux instances as convenient tools for managing and editing files. - -[image sculpt_leitzentrale 62%] - Leitzentrale subsystem - -The Leitzentrale employs two noux instances (Figure [sculpt_leitzentrale]). -With the instance on the left, you can interact with both the report and +Within the inspect window, you can interact with both the report and config file systems using familiar commands such as the bash shell, a -subset of coreutils, and Vim. The right side gives you a quick glance at the -current log messages. The log is also available at _report/log_ and can be -browsed with Vim. +subset of coreutils, and Vim. + +Besides the interactive shell, the Leitzentrale employs a noux instance that +gives you a quick glance at the most recent log messages. The log is also +available at _report/log_ and can be browsed with Vim in the inspect window. _Noux is not bullet-proof. Should you get stuck, you may re-spawn it at_ -_any time by pressing F11._ +_any time by toggling the "Inspect" button._ Tweaking and inspecting the system @@ -330,15 +340,12 @@ user - most likely discharge the latter. As mentioned in Section [Drivers subsystem], user input is processed by the input-filter component. You can edit this component's configuration via -! genode:/> vim /config/input_filter.config +! genode:/> vim /config/input_filter To change the keyboard layout to German, change "en_us.chargen" to "de.chargen" and save the file. The change becomes effective immediately at saving time. -_Note that the terminal does not display umlaut characters._ -_Please stick to using plain ASCII characters._ - To remap the capslock key to escape - a key often needed while using Vim - uncomment the corresponding '' rule @@ -368,14 +375,14 @@ displays and their supported resolutions by taking a look at the report at _/report/drivers/dynamic/intel_fb_drv/connectors_. This report is updated whenever a display is connected or disconnected. You can use this information to enable or disable a display in the driver's configuration, -which you can find at _/config/fb_drv.config_. Please don't forget to +which you can find at _/config/fb_drv_. Please don't forget to correctly specify all attributes including the 'hz' attribute. Otherwise, the driver will not consider the '' setting. For a quick test, change the attribute 'height="768"' to 'force_height="768"' (you may modify 'width' analogously). When saving the file, the screen real-estate will forcibly be limited to the specified size. This is helpful -during presentations where the beamer has a lower resolution than the +during presentations where the projector has a lower resolution than the laptop's internal display. By specifying the beamer's resolution, both the laptop and the beamer show the same content. @@ -384,7 +391,7 @@ Exploring the drivers and Leitzentrale subsystems ------------------------------------------------- You can review the construction plan of the drivers subsystem by opening the -file _/config/drivers/config_ in Vim. In particular, it is interesting to +file _/config/drivers_ in Vim. In particular, it is interesting to follow the '' rules to see how the various components are connected. But there is more. The configuration is live. It enables you to reconfigure individual components on-the-fly. For example, search for the '' node @@ -406,464 +413,228 @@ _The component-specific configuration options are documented in the README_ _files accompanying the respective components in the source tree._ Analogously to the drivers subsystem, you can find the construction plan -for the Leitzentrale subsystem at _/config/leitzentrale/config_. Try out +for the Leitzentrale subsystem at _/config/leitzentrale_. Try out the following tweaks: * Change the transparency of the two noux instances by modifying the - 'alpha' attributes of the 'control_fader' and 'log_fader' components. + 'alpha' attribute of the 'fader' component. -* Change the position and size of the two noux instances by tweaking - the coordinates ('xpos', 'ypos', 'width', 'height') of the - 'control_nit_fb' and 'log_nit_fb' components. - -* Show a simple CPU-load display by uncommenting the '' node of - the 'cpu_load_display' component. - -* Change the font size of the 'control_terminal' component from "16" - to "12". +* Change the font size of the 'log_terminal' component from "10" + to "18". You may also enjoy tinkering with the configuration of the nitpicker GUI -server, which is located at _/config/nitpicker.config_. For example, you +server, which is located at _/config/nitpicker_. For example, you may change the background color or the labeling color of the "default" domain. -Storage, networking -################### +Runtime management +################## [image sculpt_runtime_highlighted] -So far, we have not lost any word about the third subsystem called -"runtime" that lives besides the drivers and Leitzentrale subsystems. +So far, we have not lost any words on the third subsystem called +"runtime" that exists besides the drivers and Leitzentrale subsystems. The runtime subsystem has no predefined purpose but can be filled with -life as you wish. In the following, we successively reshape the content of -the runtime subsystem to perform a form of system installation. +life at your wish. -Analogously to the drivers subsystem, the live configuration of the runtime -subsystem is located at _/config/runtime/config_. Initially, it is almost -empty. +Analogously to the drivers subsystem, the current configuration of the runtime +subsystem is located at _/config/runtime_. Where the initial Sculpt EA +version required the user to control the runtime configuration manually, +Sculpt TC automates these steps through the interactive Sculpt manager that is +hosted in the Leitzentrale subsystem. You can click on any of those items to +reveal possible operations of the selected item. + +For the start, it is best to experiment with the "ram" in-memory file system. +In the previous section, we have already launched the inspect window via the +"Inspect" button of the in-memory file system. By additionally selecting the +"Use" button, we tell the Sculpt manager that we intent to use this file +system as storage location for the Sculpt session. This has two immediate +effects. First, any files present at _config//_ at the selected file +system are copied to the config file system. As the RAM file system is empty, +no files are copied. Second, the so-called _depot/_ is initialized at the +selected file system. The depot is the designated place for the installation +of software packages. By default, the depot is initialized such that the +Sculpt system accepts software published by Genode's core developers. You may +inspect the content of _/ram/depot_ using the inspect window. + +The second dialog of the menu presents options for network connectivity. +In order to install any software packages, one needs to select either +"Wired" or "Wifi". In the latter case, one is prompted with the selection +of an access point and the WPA passphrase (if needed). Once connected, the +network dialog displays the IP address of the machine. + +With a file system selected and an Internet connection, it is time to +install and run additional software. The interface for software installation +and deployment is the _/config/deploy_ file. It contains a number of +commented-out template snippets for various subsystems. As a first test, +uncomment the '' entries for the _fonts_fs_, _wm_, and _backdrop_. +When saving the file, the Sculpt manager will automatically kick off the +download of the selected packages and its dependencies and thereby +populate the depot. Once the download has completed, the packages are +started. Pay special attention to the '' definitions. They define +how the respective subsystem is connected to other parts of the system. +For example, by default, the backdrop is directly connected to the nitpicker +GUI server of the base system (parent). By changing the route from '' +to '' the backdrop subsystem will be connected to the window +manager instead. -Preparing the disk -================== +Storage device access and preparation +===================================== -It goes without saying that we want to persistently store data, programs, -and configuration information on our machine. So we need to access a block -device. Let us see if the drivers subsystem has successfully detected the -SATA disk of your machine: +Whereas the RAM file system is practical for quick tests, it goes without +saying that we want to persistently store data, programs, and configuration +information on a storage device. Sculpt TC supports SATA disks, NVMe devices, +and USB-storage devices. The storage dialog lists all devices detected by +the drivers subsystem. A click on a device reveals possible operations or - +if a partition table is present - more details about the device structure. -! genode:/> cat /report/drivers/block_devices +Depending on the operation selected by the user, the Sculpt manager will +automatically reshape the runtime subsystem to perform the selected operation. +For example, by selecting the "Format device" operation, the Sculpt manager +will create a noux instance with the selected block device mounted at +'/dev/block' and e2fsprogs mounted at '/'. The noux instance runs +'mkfs.ext2' as init process. Likewise, an existing EXT2 file system +can be checked by activating the "Check" button, which triggers the execution +of 'fsck.ext2' for the selected file system. -The report should contain one ''. The 'label' attribute denotes the -physical name, under which the drivers subsystem will hand out a block -session for this device (e.g., 'ahci-1'). If there is only one device, the -'' report features a 'default' attribute, which should -correspond to the label of the ''. Regardless of its label, this -block device is handed out as block session under the label 'default'. This -relieves the runtime subsystem from dealing with the physical label of the -device. If more than one devices are present, there is no default device. -For this guide, we assume that a 'default' block device is present. +A particularly interesting option is presented at the last partition of the +Sculpt USB stick. Initially - right after copying Sculpt's tiny disk image to +the USB stick - the partition is only a few MiB in size. However, using the +"Expand" operation, the partition can be extended to the full size of the USB +stick, which makes enough room to use the USB stick as Sculpt file system. +This clears the way for sculpting a custom live system stored entirely on +the USB stick. -[image sculpt_block_runtime] - Runtime for accessing a block device - -To format the default block device, there exists a template runtime -configuration at _/config/runtime/block.config_. Take a moment to review it -(Figure [sculpt_block_runtime]). The interesting part is a noux instance -that has a block session mounted at '/dev/block' and a few tar archives -containing bash, coreutils, Vim, and e2fsprogs mounted at '/'. Here we -have a special-tailored Unix enviroment with the sole purpose of formatting -the disk. To bring this runtime to life, simply overwrite the live -configuration with the template: - -! genode:/> cp /config/runtime/block.config /config/runtime/config - -After issuing this copy operation, the new noux instance becomes visible in -the background of the Leitzentrale. Hide the Leitzentrale by pressing F12 -to interact with noux. You need to click on noux to set the input focus. -Within noux, you can issue the following command to format your default -block device with an ext2 file system. Note that this command wipes the -original content from your block device: - -! block:/> mkfs.ext2 /dev/block - -After a few seconds, your disk should be ready to use. The block runtime is -also useful to check the consistency of your file system: - -! block:/> fsck.ext2 -pv /dev/block - - -File-system access -================== - -[image sculpt_fs_runtime 68%] - Runtime for accessing a file system - -With the default block device formatted, we can in principle store data as -files and directories. All we need is a file-system component that -translates the notion of files and directories to block-device accesses. -To fill this gap, we use a NetBSD rump kernel. More specifically, we mount -a rump kernel as a plugin into a dedicated VFS server component -(Figure [sculpt_fs_runtime]. - -As we will need the same construct in several runtime configurations, it -is convenient to wrap it inside a dedicated init instance, which can be -instantiated as a child within the runtime configuration. The configuration -for this sub init is located at _/config/subinit/default_fs.config_. It -nicely hides the technicalities of how the default file system is accessed -and is the natural hook for using more advanced disk layouts (as indicated -by the commented-out parts). - -Following the same line of thoughts, there also is a building block for an -often used noux configuration at _/config/subinit/default_noux.config_. -This noux instance has both the on-disk file system and the in-memory -config file system mounted. - -The runtime-configuration template _/config/runtime/fs.config_ combines -both building blocks. Activate it via the Leitzentrale: - -! genode:> cp /config/runtime/fs.config /config/runtime/config - -The previous (block) noux instance is replaced by a new one, which allows -you to interact with the on-disk file system mounted at _/rw/_. At this -point, you can copy data back and forth between the in-memory config file -system and the on-disk file system. +All file systems supported by Sculpt present an "Inspect" button. By toggling +this button, the selected file system becomes accessible in the inspect +window. Note that more than one file system can be inspected at a time. +Each file system will appear as a directory at the root of the inspect +directory tree, named after the corresponding device and partition number. +This way, the inspect window becomes a convenient tool for copying files +between file systems. Under the hood, the Sculpt manager spawns a file-system +component for each inspected file system, which translates the notion of files +and directories to block-device accesses. Making customizations permanent =============================== -Using the _/config/runtime/fs.config_ runtime template, you can easily -backup your customizations of the config file system to disk. By -convention, we create a directory _/rw/config/_ on the default file system: +It is possible to make any customization of the config file system +permanent by copying the modified files to a directory named +'config/' on a persistent file system where '' corresponds +to the Sculpt version number as found in the '/VERSION' file. +Each time, this file system is selected for "Use", those files will be +automatically copied to the in-memory config file system. Note that this +mechanism works even for the '/config/deploy' file, which allows one to +restore a once sculpted system composition directly at boot time. -! noux:> mkdir /rw/config +To streamline the boot procedure into a customized Sculpt system even more, +it is possible to mark one file system as default. At boot time - when the +Sculpt manager discovers the attached storage devices - it automatically +selects a file system for use according to the following order of preference: -[image sculpt_save 60%] - Saving customizations +# Partition labeled as "GENODE*" on a USB device, +# Partition labeled as "GENODE*" on a SATA or NVMe storage device, +# An entire SATA or NVMe device used as a single EXT2 file system (as devised + by Sculpt EA). -We can now selectively copy modified configurations from the config file -system to this location, e.g.: +The storage dialog hosts a convenient "Default" button that allows one +to toggle a partition label between "GENODE" and "GENODE*". For example, +the last partition of the Sculpt USB stick can be marked as default or +non-default using this button. -! noux:> cp /config/input_filter.config /rw/config/ +Examples +######## -Restoring customizations after boot -=================================== +The _config/deploy_ file contains several example subsystems that are +installed on demand when uncommenting the corresponding '' nodes. -After rebooting the system, the saved customizations won't take any -immediate effect because the boot image does not touch the default file -system. However, there is a convenient template for a runtime configuration -that copies configuration data from the default file system to the in- -memory config file system. +:'fonts_fs': A file-system server that transforms TrueType fonts into + glyph images, which become thereby accessible as virtual files. + This provides a hook for customizing the font size of any component that + uses the font server, and relieves components from depending on a specific + font-rendering library. According to the '' information, its + configuration is taken from _/config/managed/fonts_. The 'fonts_fs' + is used by the graphical terminal of the noux subsystem and the 'top_view' + application. -As you may have guessed: _/config/runtime/load.config_ utilizes a -dedicated noux instance for this job. This noux instance starts the bash -shell with the '--login' argument, which prompts bash to execute the -commands provided by the '.bash_profile' file. These commands perform the -actual copy operations. +:'wm': A window manager that displays clients in windows that can be arranged + with the mouse. -[image sculpt_load 50%] - Restoring customizations +:'backdrop': A wallpaper that adjusts itself to any screen size. -In the daily routine of using Sculpt, issuing the following command in the -Leitzentrale right after system boot does the trick: +:'nano3d': A simple software-rendering demo, which can be adjusted at runtime + by modifying its configuration. E.g., by adding a custom config node + directly inside the '' node, the appearance can be changed on the fly: + ! -! genode:/> cp /config/runtime/load.config /config/runtime/config +:'noux': A noux instance with a graphical terminal, similar to the + inspect window of the leitzentrale. Note the routing of the various + file-system sessions. -To give this a try, you may reboot your machine by editing _/config/system_. -Set the attribute 'state' to the value "reset" and save the file. +:'shared_fs': A file-system server that provides the _/shared_ sub directory + of the Sculpt file system as a new file system. A client of this server + won't see any other parts of the file system. +:'usb_devices_rom': A hook for assigning USB devices to a virtual machine, + explained in Section [Updating the USB boot device from within VirtualBox]. -Connecting to a wireless network -================================ +:'vm_fs': A file-system server that provides the _/vm/debian/_ sub directory + of the Sculpt file system as a new file system. It is explained in Section + [Hosting a guest operating system]. -The drivers subsystem does not contain any support for networking. However, -the boot image provides all the building blocks needed to establish network -connectivity at the level of the runtime subsystem. Those building blocks -are drivers for wired and wireless network devices, a component for routing -network traffic, a TCP/IP stack, and an application for downloading -content. +:'top_view': An application that shows the CPU load, similar to 'top'. -Following the pattern used for the default file system where the technical -details are nicely wrapped in the _default-fs_ building block, there exists -the sub-init configuration _/config/subinit/default_nic.config_. By -default, it contains the wireless driver, which is a port of the Intel -wireless stack from the Linux kernel and the accompanying WPA supplicant. +:'2048': A _Threes!_ inspired puzzle game running in a native Libretro runtime. -[image sculpt_wifi_runtime] - Hosting a wireless driver within the runtime subsystem +:'vbox5-tc-browser': A throw-away virtual machine for running Firefox on + TinyCore Linux. It uses VirtualBox as virtual-machine monitor. -When started, the driver requests a session to the platform driver of the -drivers subsystem. Through this session, the driver becomes able to -interact with the networking device. All other devices remain hidden from -the driver. The driver continuously scans for wireless access points at a -fixed interval and reports the results in the form of a _wlan_accesspoints_ -report. Furthermore, it requests the ROM module _wlan.config_, which -contains the authentication information needed to connect to a selected -access point (Figure [sculpt_wifi_runtime]). To give the driver a spin, -you may use the _/config/runtime/download.config_ runtime template: +:'seoul-tc-browser': The same virtual machine as 'vbox5-tc-browser' but + executed inside the light-weight Seoul virtual-machine monitor. -! genode:/> cp /config/runtime/download.config /config/runtime/config - -Depending on the platform, the driver may spill the log with a lot of -frightening messages. Don't let them intimidate you. Better look for the -interesting information: - -! genode:/> vim /report/runtime/nic/nic/wlan_accesspoints - -You should see a list of access points including their SSIDs and signal -qualities. To establish a connection to one of the access points, open -the file _/config/wlan.config_ (vim: ':e /config/wlan.config'). By opening -the _wlan.config_ file in a separate buffer, you may conveniently copy the -SSID from the _wlan_accesspoints_ report. Don't forget to specify your WPA2 -password as 'psk' (pre-shared key) attribute value. After writing the file, -the driver should become active as indicated by an influx of new log -messages. To check for the connection state, take a look at the -corresponding report: - -! genode:/> cat /report/runtime/nic/nic/wlan_state - -If everything went well, it should tell you 'state="connected"'. - -Alternatively to using the wireless driver, you may use a wired networking -driver. A snippet for a corresponding start node is provided in the -_default_nic.config_ file. Comment out the wireless driver and uncomment -the wired driver. - -_Note that the successive starting, killing, and restarting of the drivers_ -_does not work reliably on all platforms. Sometimes the device ends up_ -_in an inconsistent state, unable to establish a network connection._ -_If this happens, you'll have to reboot your machine to properly reset the_ -_device._ - -_By default, the 11N mode of the wireless driver is disabled because the_ -_wireless hardware of a few modern platforms behave unreliably otherwise._ -_You may try to set the 'use_11n' attribute in the default_nic.config_ -_to "yes" to improve the networking throughput._ - - -Downloading files -================= - -With both network connectivity and persistent storage, it is time to -download content from the internet. If you followed the steps above, the -_download_ runtime _/config/runtime/download.config_ should already be -in place. - -; default default default -; Noux ---> FS <--- chroot <--- fetchurl ---> NIC -; : : : -; : : : -; v v v -; Nitpicker Block Platform -; (PCI device) - -[image sculpt_download_runtime] - Runtime for downloading content from the network - -Figure [sculpt_download_runtime] illustrates the scenario that builds upon -the _default_noux_, _default_fs_, and _default_nic_ building blocks. The -fetchurl component should raise our concern. It has access to the file -system and is at the same time exposed to the network. A remote attacker -may exploit it as a gateway to our persistent storage. What makes matters -worse is the enormous complexity of the component, which includes protocol -implementations for TCP/IP and HTTPS (via libcurl). Vulnerabilities should -be expected. For this reason, the scenario shields the real file system -from fetchurl by using a *chroot* component, which presents the local -download directory as the file system to fetchurl. In the worst case - if -fetchurl falls completely into the hands of an attacker - the reach of the -attack is limited to the download directory. - -In the _/config/runtime/download.config_ template that we installed in the -runtime subsystem, fetchurl is commented out. Take a minute to study the -configuration of the chroot and fetchurl components. These components are -readily configured to download the ISO image of the Debian installer to the -location _/vm/debian/installer.iso_. We will use this ISO image in the -subsequent steps. - -Let's start downloading the file by uncommenting the fetchurl start node in -the runtime configuration _/config/runtime/config_ directly and saving the -file. The download of the circa 300 MiB may take a while. You may inspect -the progress by using the accompanied noux instance. - -! noux:/> ls -l /rw/vm/debian/ - - -Extending the system -#################### - -The base system discussed so far is just an intermediate step towards a real -operating system. It contains only the components necessary to reach the -second stage where software is hosted on the file system. In contrast to -the base system, which is meant to stay constant over a long time or even -used as firmware instead of a BIOS, the second stage is designed to be -expandable in arbitrary ways. The software of the second stage comes in the -form of packages facilitating a custom package-management concept that is -inspired by Git as well as the Nix package manager. - -:Non-destructive: - Installing or updating software has no effect on the already installed - software. You can always roll back your system to a previous state. - There are no install script that could mutate the system globally. - -:Multiple versions can peacefully co-exist: - Updating one package does not force you to update other, unrelated, - packages. - -:Simplicity: - There is no domain-specific language and no database. All meta data is - in plain sight. - -:Decentralized software provisioning: - There can be any number of software providers. The potential reach of - each software provider is limited to one directory each. One can even - install software from an untrusted party without any fear. - -:Accountability: - Software cannot enter the system without a proper OpenPGP signature that - attests its authenticity and integrity. - -:Low-complexity trusted computing base: - The installation mechanism sandboxes all components that are potentially - exposed to an attacker, e.g., the code that decompresses and extracts - archives, or any network-facing code. - - -Installing software -=================== - -To install software, we need the following prerequisites: - -* Storage location for downloads, -* Storage location for installed software, -* Download URL, and -* Public key of software producer. - -By convention, software is downloaded to the _/public_ directory of the -default file system whereas installed software will reside in the _/depot_ -directory. The latter also hosts the information about download URLs and -public keys. To prepare the depot, we can use a _default_noux_ instance -as featured in the _fs_ or _download_ runtime templates. - -* Create the download location - - ! noux:/> mkdir /rw/public - -* Initialize the depot for hosting the installed software. The example - provided at _/config/examples/depot/_ is equipped with the public key - and the download URL for packages originating from Genode Labs. - - ! noux:/> cp -r /config/examples/depot /rw/ - -[image sculpt_update_runtime] - Runtime for installing / updating software - -With these preparations in place, the _/config/runtime/update.config_ -runtime template can be used to install software (Figure -[sculpt_update_runtime]). Following the pattern used by the download -runtime, the access to the file system is mediated via chroot components. -The software to install is defined by _/config/installation_, which -contains a list of archives. By default, it contains a meta package called -"sculpt-installation", which contains all components needed to host a -virtual machine on top of Sculpt. To trigger the installation: - -! genode:/> cp /config/runtime/update.config /config/runtime/config - -; What's missing? <-----------------------. -; | | -; | archive list | content -; v | -; Get download info Extract -; | ^ -; | URL, pubkey | good/bad -; v | -; Fetch -------------------------> Verify -; archives, signatures - -[image depot_download 60%] - System installation as an iterative procedure - -The update runtime contains a so-called depot-download subsystem that -orchestrates the dependency tracking, downloading, verification, and -extraction of depot content. Internally, the depot-download subsystem is -composed of several components that are dynamically spawned and disposed as -needed. As illustrated by Figure [depot_download], the installation is an -iterative process, which will eventually finish with the log message -"Installation complete". - - -Deploying installed software -============================ - -Once the local depot is populated with installed software, we need to steer -Sculpt to use the new installed components instead of the ones found on the -base image. This is accomplished with the _/config/runtime/deploy.config_ -runtime template as illustrated in Figure [sculpt_deploy_runtime]. - -[image sculpt_deploy_runtime] - Runtime for deploying installed software - -The deploy runtime spawns a dynamically configured init as a subsystem. -Like any init instance, it obtains the binaries for the hosted components -as ROM modules from a ROM service. But unlike the instances we encountered -so far, which obtained ROM modules from the ROM service of the base system, -this init instance is directed to a FS-ROM component that fetches -ROM-module content from the depot. - -The last missing piece of the puzzle is a component that configures the -dynamic init instance while supplementing the information of where to look -inside the depot for the required ROM modules. This is the role of the -depot-deploy component. It takes a high-level description of the -to-be-deployed system scenario in the form of the _/config/deploy/config_ -ROM module, queries the depot for the details and ingredients of the -scenario, and generates the configuration for the dynamic init instance. -Like init, the depot-deploy component is able to dynamically respond to -updates of the _/config/deploy/config_ ROM. This enables you to dynamically -shape the deployed scenario. The configuration looks similar to init's -configuration but at higher level of abstraction. In particular, start -nodes refer to so-called runtime packages, which are provided by the depot -and nicely wrap all the low-level details into easy-to-use building blocks. - -For example, the "pkg/noux-system" package as featured in -_/config/deploy/config_ is a noux subsystem similar to the _default_noux_ -subinit. When activating the depot runtime template, the noux instance -appears. This time, however, the noux subsystem is created out of the -installed depot content: - -! genode:/> cp /config/runtime/deploy.config /config/runtime/config +:'qt5_textedit': Qt5-based text editor that is explicitly granted access to + the config file system. You may change the route to other file-system + services. For example, by specifying '' instead of + '' you can edit the shared folder of 'vm' subsystem. Hosting a guest operating system ################################ -The default scenario found at _/config/deploy/config_ contains all the +The default deploy configuration found at _/config/deploy_ contains all the pieces needed to host a virtual machine on top of Sculpt. A virtual machine -is a convenient stop-gap solution for running programs that are not yet +(VM) is a convenient stop-gap solution for running programs that are not yet available natively on Genode. It ultimately enables us to use Sculpt as day-to-day OS today. -By convention, we host the content of each virtual machine in a dedicated -directory _/vm//_ at the default file system. In Section -[Downloading files], we already downloaded the ISO image with the installer -for the Debian operating system. To run it within a virtual machine, we -additionally need a virtual disk image _(machine.vdi)_ where to install the -guest OS to, and a VirtualBox configuration file _(machine.vbox)_. You may -take the files provided at _/config/examples/vm/debian/_ as starting point, -using the noux-system instance that is already running after activating the -deploy runtime. - -! noux:/> cp /config/examples/vm/debian/* /rw/vm/debian/ +By convention, we host the content of each VM in a dedicated +directory _/vm//_ at the file system. The VM directory contains +a virtual disk image(s) as well as the VM configuration. +To install the ingredients for running Debian in the VM, +you may start the 'download_debian' subsystem, which will automatically +download the ISO image of the Debian installer and install a reasonable +VM configuration. The subsystem requests a file-system session +that points to the target directory. To pass the _/vm/debian_ directory +to the subsystem, the file-system session is routed to the 'vm_fs' component. +Please make sure to uncomment this component along with the 'download_debian' +subsystem. Please review and adjust the _machine.vbox_ file as needed, in particular you may reconsider the amount of RAM by changing the 'RAMSize' attribute. -To start the virtual machine, uncomment the following commented-out parts -of _/config/deploy/config_: +To start the VM, remove the comments around the following snippets within +_/config/deploy_: -# One of the two NIC drivers (either wifi or ipxe_nic_drv), -# The NIC router, which sits in-between the NIC driver and the virtual - machine, and plays the role of a virtual NAT router, and -# The start nodes of "vm_fs", "shared_fs", "usb_devices_rom", and "vm". +# "wm" - the window manager that will host a window of the VM, +# "vm_fs" - the location of the virtual-disk image and VM configuration, +# "shared_fs" - the location for sharing files between the guest OS and + other parts of the Sculpt system, +# "usb_devices_rom" - a configuration that contains a list of USB devices + passed to the VM, +# "vm" - the virtual machine. After saving the file, VirtualBox should appear, starting the Debian installer. @@ -912,6 +683,59 @@ it can be mounted and accessed via '/mnt'. Advanced usage ############## +Manual configuration +==================== + +Thanks to the Sculpt manager component of the Leitzentrale, many typical +work flows and configuration tweaks are largely automated. For example, + +* The management of storage devices, +* The creation of file-system components for used or inspected file systems, +* The selection and configuration of network access, +* Font size selection depending on the screen resolution, +* Triggering the download of missing depot content on demand. + +This convenience comes at the price of built-in policy, which may stand in +the way of sophisticated scenarios. For this reason, almost all policies +of the Sculpt manager can be manually overriden by manually managing +configuration files. + +The Sculpt manager interacts with the rest of the system solely by +monitoring reports aggregated in the report file system, and writing +configuration files into the config file systems. All files generated +by the Sculpt manager are located at _/config/managed/_. By manually creating a +same-named file at _/config/_, one can supply a custom managed configuration +to the Sculpt manager. A useful practice is taking a snapshot of the +generated configuration as a starting point for the custom version. For +example, by copying the NIC router configuration while it is connected to +a network: + +! cp /config/managed/nic_router /config + +Now, the copy at _/config/nic_router_ can be edited. Note that changes +usually take immediate effect. + +Examples of manual customization are: +* Adding custom NIC router policies such as port-forwarding rules, +* Installing depot content manually by managing _/config/installation_ + by hand. This includes the ability to download the source code for + any package. +* Disarming the automated update mechanism by using a _/config/installation_ + file with no '' entries. +* Fixing the current state of the runtime subsystem by copying + _/config/managed/runtime_ to _/config/runtime_. This allows one to + manually tweak and inspect the runtime in any way, e.g., to enable + additional reporting when troubleshooting. +* Manually defining the default font sizes by creating a custom _config/fonts_ + configuration. +* Managing Wifi credentials manually by supplying a custom _config/wlan_ file. + +To revert any manual customization, delete the corresponding file. In this +case, the Sculpt manager will take over again. Note that all manual +customizations can be made permanent by following the steps explained in +Section [Making customizations permanent]. + + Reproducing the system from source ================================== @@ -981,22 +805,10 @@ version. For more information about working with the depot tool, refer to [http://genode.org/documentation/developer-resources/package_management]. -UEFI boot -========= - -By default, the steps given in Section [Building the boot image] produce a -legacy-boot ISO image, which requires a BIOS. To create an UEFI image -instead, modify your '/etc/build.conf' by replacing 'image/iso' -by 'image/uefi'. When executing the _sculpt.run_ script now, an UEFI image -is created at _build/x86_64/var/run/sculpt.img_. It is a disk image -containing an UEFI partition with all the content needed. It can be -directly written to a USB stick. - - Updating the USB boot device from within VirtualBox =================================================== -The _/config/deploy/config_ scenario is prepared to assign USB storage +The _/config/deploy_ example is prepared to assign USB storage devices directly to a running virtual machine. You may inspect the report _/report/drivers/usb_active_config_ to get a list of attached USB devices. Use Vim to copy the '' node of the selected device into the @@ -1008,7 +820,7 @@ _/config/deploy/config_, and adjust the line as follows: The updated 'usb_devices' ROM prompts VirtualBox to open a USB session at the drivers subsystem. Hence, when saving the modified -_/config/deploy/config_ file, the guest OS should detect a new USB device +_/config/deploy_ file, the guest OS should detect a new USB device (check the output of 'dmesg'). You may now write a new version of the Sculpt ISO image to the device by following the steps described in Section [Building the boot image].