https://wiki.archlinux.org/api.php?action=feedcontributions&user=Luto&feedformat=atomArchWiki - User contributions [en]2024-03-28T09:31:31ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Archiso&diff=762352Archiso2022-12-28T15:35:56Z<p>Luto: add instructions how to use auto login with serial console</p>
<hr />
<div>[[Category:Live Arch systems]]<br />
[[Category:Installation process]]<br />
[[Category:Arch projects]]<br />
[[es:Archiso]]<br />
[[fr:Archiso]]<br />
[[ja:Archiso]]<br />
[[pt:Archiso]]<br />
[[ru:Archiso]]<br />
[[zh-hans:Archiso]]<br />
{{Related articles start}}<br />
{{Related|Archiso as pxe server}}<br />
{{Related|Offline installation}}<br />
{{Related|USB flash installation medium}}<br />
{{Related articles end}} <br />
[https://gitlab.archlinux.org/archlinux/archiso Archiso] is a highly-customizable tool for building Arch Linux live CD/USB ISO images. The [https://archlinux.org/download/ official images] are built with Archiso. It can be used as the basis for rescue systems, linux installers or other systems. This wiki article explains how to install Archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs official project documentation]. Archiso is implemented with a number of bash scripts. The core component of Archiso is the ''mkarchiso'' command. Its options are documented in ''mkarchiso -h'' and not covered here.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package. The {{AUR|archiso-profiles}} package contains additional community-provided profiles.<br />
<br />
== Prepare a custom profile ==<br />
<br />
Archiso comes with two profiles, '''releng''' and '''baseline'''.<br />
<br />
* '''releng''' is used to create the official monthly installation ISO. It can be used as a starting point for creating a customized ISO image.<br />
* '''baseline''' is a minimalistic configuration, that includes only the bare minimum packages required to boot the live environment from the medium.<br />
<br />
To build an unmodified version of the profiles, skip to [[#Build the ISO]]. Otherwise, if you wish to adapt or customize one of archiso's shipped profiles, copy it from {{ic|/usr/share/archiso/configs/''profile-name''/}} to a writable directory with a name of your choice. For example:<br />
<br />
$ cp -r /usr/share/archiso/configs/releng/ archlive<br />
<br />
Proceed to the following sections to customize and build the custom profile.<br />
<br />
=== Profile structure ===<br />
<br />
An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in {{ic|/usr/share/doc/archiso/README.profile.rst}}[https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst].<br />
<br />
=== Selecting packages ===<br />
<br />
Edit {{ic|packages.x86_64}} to select which packages are to be installed on the live system image, listing packages line by line.<br />
<br />
==== Custom local repository ====<br />
<br />
To add packages not located in standard Arch repositories (e.g. custom packages or packages from [[AUR]]/[[ABS]]), set up a [[custom local repository]] and add your custom packages to it. Then add your repository to {{ic|pacman.conf}} as follows: <br />
<br />
{{hc|''archlive''/pacman.conf|2=<br />
...<br />
[''customrepo'']<br />
SigLevel = Optional TrustAll<br />
Server = file://''/path/to/customrepo''<br />
...<br />
}}<br />
<br />
{{Note|The ordering within {{ic|pacman.conf}} matters. To give top priority to your custom repository, place it above the other repository entries.}}<br />
<br />
==== Packages from multilib ====<br />
<br />
To install packages from the [[multilib]] repository, simply uncomment that repository in {{ic|pacman.conf}}.<br />
<br />
=== Adding files to image ===<br />
<br />
The airootfs directory is used as the starting point for the [[Wikipedia:Root directory|root directory]] ({{ic|/}}) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.<br />
<br />
Place any custom files and/or directories in the desired location under {{ic|airootfs/}}. For example, if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:<br />
<br />
$ cp -r /etc/iptables ''archlive''/airootfs/etc<br />
<br />
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with {{man|1|mkdir}}.<br />
<br />
{{Tip|To add a file to the install user's home directory, place it in {{ic|''archlive''/airootfs/root/}}. To add a file to all other users home directories, place it in {{ic|''archlive''/airootfs/etc/skel/}}.}}<br />
<br />
{{Note|Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as [[pacman/Pacnew and Pacsave#Package backup files|backup files]].}}<br />
<br />
By default, [[permissions]] will be {{ic|644}} for files and {{ic|755}} for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the {{ic|file_permissions}} associative array in {{ic|profiledef.sh}}. See [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst README.profile.rst] for details.<br />
<br />
=== Kernel ===<br />
<br />
Although both archiso's included profiles only have {{Pkg|linux}}, ISOs can be made to include other or even multiple [[kernels]].<br />
<br />
First, edit {{ic|packages.x86_64}} to include kernel package names that you want. When ''mkarchiso'' runs, it will include all {{ic|''work_dir''/airootfs/boot/vmlinuz-*}} and {{ic|''work_dir''/boot/initramfs-*.img}} files in the ISO (and additionally in the FAT image used for UEFI booting).<br />
<br />
[[mkinitcpio]] presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the {{ic|autodetect}} hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in {{ic|''archlive''/airootfs/etc/mkinitcpio.d/''pkgbase''.preset}}. For example, for {{Pkg|linux-lts}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/mkinitcpio.d/linux-lts.preset|2=<br />
PRESETS=('archiso')<br />
<br />
ALL_kver='/boot/vmlinuz-linux-lts'<br />
ALL_config='/etc/mkinitcpio.conf'<br />
<br />
archiso_image="/boot/initramfs-linux-lts.img"<br />
}}<br />
<br />
Finally create [[#Boot loader|boot loader configuration]] to allow booting the kernel(s).<br />
<br />
=== Boot loader ===<br />
<br />
Archiso supports [[syslinux]] for BIOS booting and [[systemd-boot]] for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* The '''releng''' profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using [https://wiki.syslinux.org/wiki/index.php?title=Isohybrid Isohybrid].<br />
* Due to the modular nature of isolinux, you are able to use lots of addons since all ''.c32'' files are copied and available to you. Take a look at the [https://wiki.syslinux.org/wiki/index.php/SYSLINUX official syslinux site] and the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng/syslinux archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [https://wiki.syslinux.org/wiki/index.php/Comboot/menu.c32].<br />
}}<br />
<br />
mkarchiso expects that [[systemd-boot]] configuration is in the {{ic|efiboot}} directory, and [[syslinux]] configuration in {{ic|syslinux}} and {{ic|isolinux}} directories.<br />
<br />
==== UEFI Secure Boot ====<br />
<br />
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader. You can follow the instructions on [[Secure Boot#Booting an installation medium]].<br />
<br />
=== systemd units ===<br />
<br />
To [[enable]] systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as {{ic|systemctl enable}} does it.<br />
<br />
For example, to enable {{ic|gpm.service}}, which contains {{ic|1=WantedBy=multi-user.target}}, run:<br />
<br />
$ mkdir -p ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/gpm.service ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by [[enabling]] it and observing the systemctl output.<br />
<br />
==== Login manager ====<br />
<br />
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you do not know which ''.service'' to enable, you can easily find out in case you are using the same program on the system you build your ISO on. Just use:<br />
<br />
$ ls -l /etc/systemd/system/display-manager.service<br />
<br />
Now create the same symlink in {{ic|''archlive''/airootfs/etc/systemd/system/}}. For LXDM:<br />
<br />
$ ln -s /usr/lib/systemd/system/lxdm.service ''archlive''/airootfs/etc/systemd/system/display-manager.service<br />
<br />
This will enable LXDM at system start on your live system.<br />
<br />
==== Changing automatic login ====<br />
<br />
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.<br />
<br />
You can modify this file to change the auto login user:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty --autologin '''''username''''' --noclear %I 38400 linux<br />
<br />
Or remove {{ic|autologin.conf}} altogether to disable auto login.<br />
<br />
If you are using the serial console, create {{ic|airootfs/etc/systemd/system/serial-getty@ttyS0.service.d/autologin.conf}} with the following content instead:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty -o '-p -- \\u' --noclear --autologin root --keep-baud 115200,57600,38400,9600 - $TERM<br />
<br />
=== Users and passwords ===<br />
<br />
To create a [[user]] which will be available in the live environment, you must manually edit {{ic|''archlive''/airootfs/etc/passwd}}, {{ic|''archlive''/airootfs/etc/shadow}}, {{ic|''archlive''/airootfs/etc/group}} and {{ic|''archlive''/airootfs/etc/gshadow}}.<br />
<br />
{{Note|If these files exist, they must contain the root user and group.}}<br />
<br />
For example, to add a user {{ic|archie}}. Add them to {{ic|''archlive''/airootfs/etc/passwd}} following the {{man|5|passwd}} syntax:<br />
<br />
{{hc|''archlive''/airootfs/etc/passwd|<br />
root:x:0:0:root:/root:/usr/bin/zsh<br />
archie:x:1000:1000::/home/archie:/usr/bin/zsh<br />
}}<br />
<br />
Generate a password hash with {{ic|openssl passwd -6}} and add it to {{ic|''archlive''/airootfs/etc/shadow}} following the syntax of {{man|5|shadow}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/shadow|2=<br />
root::14871::::::<br />
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::<br />
}}<br />
<br />
Add the user's group and the groups which they will part of to {{ic|''archlive''/airootfs/etc/group}} according to {{man|5|group}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/group|2=<br />
root:x:0:root<br />
adm:x:4:archie<br />
wheel:x:10:archie<br />
uucp:x:14:archie<br />
archie:x:1000:<br />
}}<br />
<br />
Create the appropriate {{ic|''archlive''/airootfs/etc/gshadow}} according to {{man|5|gshadow}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/gshadow|2=<br />
root:!*::root<br />
archie:!*::<br />
}}<br />
<br />
Make sure {{ic|/etc/shadow}} and {{ic|/etc/gshadow}} have the correct permissions:<br />
<br />
{{hc|''archlive''/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/etc/shadow"]="0:0:0400"<br />
["/etc/gshadow"]="0:0:0400"<br />
)<br />
}}<br />
<br />
After package installation, ''mkarchiso'' will create all specified home directories for users listed in {{ic|''archlive''/airootfs/etc/passwd}} and copy {{ic|''work_directory''/x86_64/airootfs/etc/skel/*}} to them. The copied files will have proper user and group ownership.<br />
<br />
=== Changing the distribution name used in the ISO ===<br />
<br />
Start by copying the file {{ic|/etc/os-release}} into the {{ic|etc/}} folder in the rootfs. Then, edit the file accordingly. You can also change the name inside of GRUB and syslinux.<br />
<br />
== Build the ISO ==<br />
<br />
Build an ISO which you can then burn to CD or USB by running:<br />
<br />
# mkarchiso -v -w ''/path/to/work_dir'' -o ''/path/to/out_dir'' ''/path/to/profile/''<br />
<br />
* {{ic|-w}} specifies the working directory. If the option is not specified, it will default to {{ic|work}} in the current directory.<br />
* {{ic|-o}} specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to {{ic|out}} in the current directory.<br />
* It should be noted the profile file {{ic|profiledef.sh}} cannot be specified when running mkarchiso, only the path to the file.<br />
<br />
Replace {{ic|''/path/to/profile/''}} with the path to your custom profile, or with {{ic|/usr/share/archiso/configs/releng/}} if you are building an unmodified profile.<br />
<br />
{{Tip|If memory allows, it is preferred to place the working directory on [[tmpfs]]. E.g.:<br />
<br />
# mkarchiso -v -w /tmp/archiso-tmp ''/path/to/profile/''<br />
<br />
}}<br />
<br />
When run, the script will download and install the packages you specified to {{ic|''work_directory''/x86_64/airootfs}}, create the kernel and init images, apply your customizations and finally build the ISO into the output directory.<br />
<br />
=== Removal of work directory ===<br />
<br />
{{Warning|If ''mkarchiso'' is interrupted, run {{man|8|findmnt}} to make sure there are no mount binds before deleting it - otherwise, '''you may lose data''' (e.g. an external device mounted at {{ic|/run/media/''user''/''label''}} gets bound within {{ic|work/x86_64/airootfs/run/media/''user''/''label''}} during the build process).}}<br />
<br />
The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:<br />
<br />
# rm -rf ''/path/to/work_dir''<br />
<br />
== Using the ISO ==<br />
<br />
See [[Installation guide#Prepare an installation medium]] for various options.<br />
<br />
== Test the ISO in QEMU ==<br />
<br />
[[Install]] the optional dependencies {{pkg|qemu-desktop}} and {{pkg|edk2-ovmf}}.<br />
<br />
Use the convenience script {{ic|run_archiso}} to run a built image using [[QEMU]].<br />
<br />
$ run_archiso -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
The virtual machine can also be run using UEFI emulation:<br />
<br />
$ run_archiso -u -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
== Tips and tricks ==<br />
<br />
=== Online build ===<br />
<br />
If you do not have an arch system available or you need to setup Archiso from another GNU/Linux distribution, be aware there exists an [https://colab.research.google.com/github/tallero/archiso-profiles/ online builder].<br />
<br />
=== Prepare an ISO for an installation via SSH ===<br />
<br />
{{Note|Since {{ic|archlinux-2021.02.01-x86_64.iso}}, [https://gitlab.archlinux.org/archlinux/archiso/-/tree/bd2b861aa39167e4fc658a354071b95fbd050c0f/configs/releng/airootfs/etc/systemd/system/cloud-init.target.wants cloud-init support] is provided, and {{ic|sshd.service}} is [https://gitlab.archlinux.org/archlinux/archiso/-/blob/bd2b861aa39167e4fc658a354071b95fbd050c0f/configs/releng/airootfs/etc/systemd/system/multi-user.target.wants/sshd.service enabled by default].}}<br />
<br />
To [[install Arch Linux via SSH]] without any interaction with the system, an SSH public key must be placed in {{ic|authorized_keys}}.<br />
<br />
Adding the SSH key can either be done manually (explained here), or [[Install Arch Linux via SSH#Installation on a headless server|by cloud-init]].<br />
<br />
To add the key manually, first [[#Prepare a custom profile|copy Archiso's releng profile]] to a writable directory. The following example uses {{ic|archlive}}.<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile/'' archlive<br />
<br />
Create a {{ic|.ssh}} directory in the home directory of the user which will be used to log in. The following example will be using the root user.<br />
<br />
$ mkdir archlive/airootfs/root/.ssh<br />
<br />
Add the SSH public key(s), which will be used to log in, to {{ic|authorized_keys}}:<br />
<br />
$ cat ~/.ssh/''key1''.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
$ cat ~/.ssh/''key2''.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
<br />
Set correct [[permissions]] and ownership for the {{ic|.ssh}} directory and the {{ic|authorized_keys}} file:<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/root"]="0:0:0750"<br />
["/root/.ssh"]="0:0:0700"<br />
["/root/.ssh/authorized_keys"]="0:0:0600"<br />
)<br />
}}<br />
<br />
Finally [[#Build the ISO|build the ISO]]. Upon booting the ISO, [[OpenSSH]] will start and it will be possible to log in using the corresponding SSH private key(s).<br />
<br />
=== Automatically connect to a Wi-Fi network using iwd ===<br />
<br />
Create {{ic|/var/lib/iwd/}} inside the profile's {{ic|airootfs}} directory and set the correct permissions:<br />
<br />
$ mkdir -p ''archlive''/airootfs/var/lib/iwd<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/var/lib/iwd"]="0:0:0700"<br />
)<br />
}}<br />
<br />
Follow the instructions in [[iwd#Network configuration]] and {{man|5|iwd.network}} to create a network configuration file for your Wi-Fi network.<br />
<br />
Save the configuration file inside {{ic|''archlive''/airootfs/var/lib/iwd/}}.<br />
<br />
=== Adjusting the size of root partition on the fly ===<br />
<br />
When installing packages on a live Archiso, for example on hardware requiring [[DKMS]] modules, the default size of the Archiso might not allow the download and installation of such packages due to its size. <br />
<br />
It will manifest as the following error message when downloading files or installing packages in the live environment: <br />
<br />
error: partition / too full: 63256 blocks needed, 61450 blocks free<br />
error: not enough free disk space<br />
error: failed to commit transaction (not enough free disk space) <br />
Errors occurred: no packages were upgraded.<br />
<br />
You can also adjust the root partition size on the fly by running: <br />
<br />
# mount -o remount,size=2G /run/archiso/cowspace<br />
<br />
To adjust the size of the root partition on the live Arch Linux system before booting it, press the {{ic|Tab}} key to edit the kernel parameters. Append {{ic|1=cow_spacesize=2G}} at the end to get 2G size for the root partition.<br />
Press {{ic|Enter}} to continue booting into the live system.<br />
You can check the size of the filesystems by running:<br />
<br />
$ df -h<br />
<br />
See more boot parameters [https://gitlab.archlinux.org/mkinitcpio/mkinitcpio-archiso/blob/master/docs/README.bootparams here]<br />
<br />
=== Encryption ===<br />
<br />
In order for vanilla {{ic|mkarchiso}} to produce encrypted images, [[LUKS]] support in [https://gitlab.archlinux.org/archlinux/archiso/-/merge_requests/217 archiso], [[dm-crypt/System configuration|encrypt]] hook's compatibility in [https://gitlab.archlinux.org/mkinitcpio/mkinitcpio-archiso/-/merge_requests/25 mkinitcpio-archiso] and nested {{ic|cryptkey}}s support in {{Pkg|cryptsetup}} merge requests need to be approved.<br />
<br />
Packages with such features already merged are {{AUR|archiso-encryption}}, {{AUR|mkinitcpio-archiso-encryption}} and {{AUR|cryptsetup-nested-cryptkey}}.<br />
<br />
To enable encryption on an existing profile: <br />
* add {{ic|+luks}} to the {{ic|airootfs_image_type}} value in {{ic|profiledef.sh}};<br />
* set an {{ic|encryption_key}} in {{ic|profiledef.sh}} (to use a key file instead of a password).<br />
* enable the {{ic|encrypt}} hook in {{ic|/etc/mkinitcpio.conf}};<br />
* add AUR packages (or build custom replacements with the aforementioned sources) to {{ic|packages.x86_64}}<br />
* add the {{ic|keys}} buildmode to the {{ic|buildmodes}} array in {{ic|profiledef.sh}} (to build a second ISO containing the key file that put on external storage is able to boot the system).<br />
<br />
Example configurations based on the {{ic|baseline}} and {{ic|releng}} profiles are available as {{ic|ebaseline}} and {{ic|ereleng}} in the {{AUR|archiso-profiles}} package.<br />
<br />
=== Google Compute Engine images ===<br />
<br />
A Google Compute Engine-compatible {{ic|releng}} compressed image is available as {{AUR|archlinux-gce}}.<br />
<br />
=== Libvirt VM configuration ===<br />
<br />
A [[libvirt]] configuration which runs the {{ic|releng}} image is available as {{AUR|archlinux-libvirt}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Window manager freezes ===<br />
<br />
If you want to use a [[window manager]] in the Live CD, you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.archlinux.org/archlinux/archiso Archiso project page]<br />
* [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs Official documentation]<br />
* [https://lists.archlinux.org/mailman3/lists/arch-releng.lists.archlinux.org/ Arch Linux Release Engineering mailing list]<br />
* [ircs://irc.libera.chat/archlinux-releng #archlinux-releng — Arch Linux Release Engineering IRC channel]<br />
* [https://github.com/pierres/archiso-manager archiso-manager — the tool used for building the official monthly ISOs]</div>Lutohttps://wiki.archlinux.org/index.php?title=Subtle&diff=286203Subtle2013-12-04T09:29:19Z<p>Luto: the default config of sublet changed, sublets do not need to be enabled manually anymore</p>
<hr />
<div>[[Category:Tiling WMs]]<br />
[[de:Subtle]]<br />
[[ko:Subtle]]<br />
From [http://subforge.org/projects/subtle Subtle project page]:<br />
:''Subtle is a manual tiling window manager with a rather uncommon approach of tiling: Instead of relying on predefined layouts, Subtle divides the screen into a grid with customizable slots (called gravities).''<br />
<br />
Subtle is configured with [[Ruby]] for [[Xorg]].<br />
<br />
{{Note|This article only explain the basics of Subtle. In depth information and tutorials exist at the [http://subforge.org/projects/subtle Subtle project page].}}<br />
<br />
==Installing==<br />
The {{pkg|subtle}} package is available in the [[Official Repositories|official repositories]]. It can be installed with [[pacman]].<br />
<br />
A developer snapshot is available in the [[AUR]] named {{AUR|subtle-hg}}.<br />
<br />
==Starting Subtle==<br />
To start Subtle add {{ic|exec subtle}} to your {{ic|.xinitrc}} file and launch Xorg. Remember that Subtle does not provide any icons or menus, and the only predefined key binding that opens a terminal is {{ic|Super+Enter}}, which will open [[URxvt]]. So if you do not have URxvt, either install it or change the configuration file before starting. If you need to exit Subtle press {{ic|Super+Ctrl+q}}.<br />
<br />
==Basic function==<br />
When windows are opened they are matched against a set of user-defined rules to get proper position and size. The process of applying these rules can be broken down in three main parts:<br />
*View<br />
*Gravity<br />
*Tag<br />
''Views'' are the environment in which the windows will be placed. Much like ordinary desktop surfaces. Defining the actual rules for a window is accomplished with a ''tag''. In tags you also determine the ''gravity'' to be used. Gravities control the size and position of windows.<br />
<br />
{{Note|When configuring Subtle you actually need to declare these elements in reverse order. Gravity, tag then view.}}<br />
<br />
==Configuration==<br />
Subtle will search for {{ic|subtle.rb}} in your $XDG_CONFIG_HOME path. If it is non-existant it will load a default file from your $XDG_CONFIG_DIRS path. It is preferable to copy this file to your {{ic|$XDG_CONFIG_HOME/subtle}} directory instead of using the default.<br />
<br />
The default file will contain numerous gravities, tags and views. This is an excellent place to start when designing your own environment. Applications without matching tags will be placed on the view containing the default tag, if no view posses it, they are automatically placed on the first view.<br />
<br />
To check your configuration file for potential errors, simply run the following command:<br />
$ subtle -k<br />
<br />
==Sublets==<br />
Sublets are tiny apps that appear in the Subtle panels. They can be used to control various applications and show system stats.<br />
<br />
===Installing sublets===<br />
To install a sublet, type the following command in a terminal:<br />
$ sur install <name of sublet><br />
<br />
For a list of sublets, go to the [http://sur.subforge.org sur website].<br />
<br />
{{Note|If you install a sublet as root, you will not be able to invoke the sublet as a regular user. Sublets used by non-root accounts must be installed under the user.}}<br />
<br />
===Enabling sublets===<br />
By default all sublets are displayed in the top right corner. You can change this behavior in {{ic|subtle.rb}} by removing {{ic|:sublets}} from the screen config and adding your sublets like this:<br />
{{bc|<nowiki><br />
screen 1 do<br />
top [ :title, :spacer, :views ]<br />
bottom [ :mpd, :wifi, :battery ]<br />
end<br />
</nowiki>}}<br />
Then just add the sublets name in the same fashion as the other ones, like this:<br />
{{bc|<nowiki><br />
bottom [ :mpd, :<name of sublet>, :wifi, :battery ]<br />
</nowiki>}}<br />
It can of course be inserted at a place by your own choice.<br />
<br />
==See also==<br />
* [http://subforge.org/projects/subtle Subtle project page]<br />
* [http://sur.subforge.org Sublets archive]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=71783 The subtle thread]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=112486 Share your Subtle desktop!]<br />
* [[xinitrc]]<br />
* [[Start X at Login]]<br />
* [[Window Manager]]</div>Luto