| index : archinstall32 | |
| Archlinux32 installer | gitolite user |
| summaryrefslogtreecommitdiff |
| -rw-r--r-- | README.md | 291 |
@@ -6,171 +6,204 @@ [](https://github.com/archlinux/archinstall/actions/workflows/flake8.yaml) Just another guided/automated [Arch Linux](https://wiki.archlinux.org/index.php/Arch_Linux) installer with a twist. -The installer also doubles as a python library to install Arch Linux and manage services, packages and other things inside the installed system *(Usually from a live medium)*. +The installer also doubles as a python library to install Arch Linux and manage services, packages, and other things inside the installed system *(Usually from a live medium)*. * archinstall [discord](https://discord.gg/cqXU88y) server * archinstall [matrix.org](https://app.element.io/#/room/#archinstall:matrix.org) channel * archinstall [#archinstall@irc.libera.chat](irc://#archinstall@irc.libera.chat:6697) -* archinstall [documentation](https://archinstall.readthedocs.io/) +* archinstall [documentation](https://archinstall.archlinux.page/) # Installation & Usage +```shell +sudo pacman -S archinstall +``` - $ sudo pacman -S archinstall +Alternative ways to install are `git clone` the repository or `pip install --upgrade archinstall`. -Or simply `git clone` the repo as it has no external dependencies *(but there are optional ones)*.<br> -Or use `pip install --upgrade archinstall` to use as a library. +## Running the [guided](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) installer -## Running the [guided](https://github.com/archlinux/archinstall/blob/master/examples/guided.py) installer +Assuming you are on an Arch Linux live-ISO or installed via `pip`: +```shell +archinstall +``` -Assuming you are on an Arch Linux live-ISO: +## Running the [guided](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) installer using `git` - # archinstall +```shell + # cd archinstall-git + # python -m archinstall +``` -Some additional options that are not needed by most users are hidden behind the `--advanced` flag. +#### Advanced +Some additional options that most users do not need are hidden behind the `--advanced` flag. ## Running from a declarative configuration file or URL -Prerequisites: - 1. Edit the [configuration file](https://github.com/archlinux/archinstall/blob/master/examples/config-sample.json) according to your requirements. +`archinstall` can be run with a JSON configuration file. There are 2 different configuration files to consider, +the `user_configuration.json` contains all general installation configuration, whereas the `user_credentials.json` +contains the sensitive user configuration such as user password, root password, and encryption password. -Assuming you are on a Arch Linux live-ISO and booted into EFI mode. +An example of the user configuration file can be found here +[configuration file](https://github.com/archlinux/archinstall/blob/master/examples/config-sample.json) +and an example of the credentials configuration here +[credentials file](https://github.com/archlinux/archinstall/blob/master/examples/creds-sample.json). - # archinstall --config <path to user config file or URL> --disk-layout <path to disk layout config file or URL> --creds <path to user credentials config file or URL> - -# Available Languages +**HINT:** The configuration files can be auto-generated by starting `archinstall`, configuring all desired menu +points and then going to `Save configuration`. -Archinstall is available in different languages which have been contributed and are maintained by the community. -Current translations are listed below and vary in the amount of translations per language -``` -English -Deutsch -Español -Français -Indonesian -Italiano -Nederlands -Polskie -Português do Brasil -Português -Svenska -Türkçe -čeština -Русский -اردو -Ελληνικά -தமிழ் +To load the configuration file into `archinstall` run the following command +```shell +archinstall --config <path to user config file or URL> --creds <path to user credentials config file or URL> ``` -Any contributions to the translations are more than welcome, and to get started please follow [the guide](https://github.com/archlinux/archinstall/blob/master/archinstall/locales/README.md) +# Help or Issues -# Help? +If you come across any issues, kindly submit your issue here on Github or post your query in the +[discord](https://discord.gg/cqXU88y) help channel. -Submit an issue here on GitHub, or submit a post in the discord help channel.<br> -When doing so, attach the `/var/log/archinstall/install.log` to the issue ticket. This helps us help you! +When submitting an issue, please: +* Provide the stacktrace of the output if applicable +* Attach the `/var/log/archinstall/install.log` to the issue ticket. This helps us help you! + * To extract the log from the ISO image, one way is to use<br> + ```shell + curl -F'file=@/var/log/archinstall/install.log' https://0x0.st + ``` -# Mission Statement -Archinstall promises to ship a [guided installer](https://github.com/archlinux/archinstall/blob/master/examples/guided.py) that follows -the [Arch Principles](https://wiki.archlinux.org/index.php/Arch_Linux#Principles) as well as a library to manage services, packages and other Arch Linux aspects. +# Available Languages -The guided installer will provide user-friendly options along the way, but the keyword here is options, they are optional and will never be forced upon anyone. -The guided installer itself is also optional to use if so desired and not forced upon anyone. +Archinstall is available in different languages which have been contributed and are maintained by the community. +The language can be switched inside the installer (first menu entry). Bear in mind that not all languages provide +full translations as we rely on contributors to do the translations. Each language has an indicator that shows +how much has been translated. ---- +Any contributions to the translations are more than welcome, +to get started please follow [the guide](https://github.com/archlinux/archinstall/blob/master/archinstall/locales/README.md) -Archinstall has one fundamental function which is to be a flexible library to manage services, packages and other aspects inside the installed system. -This library is in turn used by the provided guided installer but is also for anyone who wants to script their own installations. +## Fonts +The ISO does not ship with all fonts needed for different languages. +Fonts that use a different character set than Latin will not be displayed correctly. If those languages +want to be selected then a proper font has to be set manually in the console. -Therefore, Archinstall will try its best to not introduce any breaking changes except for major releases which may break backwards compatibility after notifying about such changes. +All available console fonts can be found in `/usr/share/kbd/consolefonts` and set with `setfont LatGrkCyr-8x16`. # Scripting your own installation -You could just copy [guided.py](https://github.com/archlinux/archinstall/blob/master/examples/guided.py) as a starting point. - -However, assuming you're building your own ISO and want to create an automated installation process, or you want to install virtual machines onto local disk images, here is a [minimal example](https://github.com/archlinux/archinstall/blob/master/examples/minimal.py) of how to install using archinstall as a Python library:<br> +## Scripting interactive installation -```python -import archinstall, getpass - -# Select a harddrive and a disk password -harddrive = archinstall.select_disk(archinstall.all_blockdevices(partitions=False)) -disk_password = getpass.getpass(prompt='Disk password (won\'t echo): ') - -# We disable safety precautions in the library that protects the partitions -harddrive.keep_partitions = False +There are some examples in the `examples/` directory that should serve as a starting point. -# First, we configure the basic filesystem layout -with archinstall.Filesystem(harddrive, archinstall.GPT) as fs: - # We create a filesystem layout that will use the entire drive - # (this is a helper function, you can partition manually as well) - fs.use_entire_disk(root_filesystem_type='btrfs') +The following is a small example of how to script your own *interactive* installation: - boot = fs.find_partition('/boot') - root = fs.find_partition('/') - - boot.format('vfat') +```python +from pathlib import Path + +from archinstall import Installer, ProfileConfiguration, profile_handler, User +from archinstall.default_profiles.minimal import MinimalProfile +from archinstall.lib.disk.device_model import FilesystemType +from archinstall.lib.disk.encryption_menu import DiskEncryptionMenu +from archinstall.lib.disk.filesystem import FilesystemHandler +from archinstall.lib.interactions.disk_conf import select_disk_config + +fs_type = FilesystemType('ext4') + +# Select a device to use for the installation +disk_config = select_disk_config() + +# Optional: ask for disk encryption configuration +data_store = {} +disk_encryption = DiskEncryptionMenu(disk_config.device_modifications, data_store).run() + +# initiate file handler with the disk config and the optional disk encryption config +fs_handler = FilesystemHandler(disk_config, disk_encryption) + +# perform all file operations +# WARNING: this will potentially format the filesystem and delete all data +fs_handler.perform_filesystem_operations() + +mountpoint = Path('/tmp') + +with Installer( + mountpoint, + disk_config, + disk_encryption=disk_encryption, + kernels=['linux'] +) as installation: + installation.mount_ordered_layout() + installation.minimal_installation(hostname='minimal-arch') + installation.add_additional_packages(['nano', 'wget', 'git']) + + # Optionally, install a profile of choice. + # In this case, we install a minimal profile that is empty + profile_config = ProfileConfiguration(MinimalProfile()) + profile_handler.install_profile_config(installation, profile_config) + + user = User('archinstall', 'password', True) + installation.create_users(user) +``` - # Set the flag for encrypted to allow for encryption and then encrypt - root.encrypted = True - root.encrypt(password=disk_password) +This installer will perform the following actions: -with archinstall.luks2(root, 'luksloop', disk_password) as unlocked_root: - unlocked_root.format(root.filesystem) - unlocked_root.mount('/mnt') +* Prompt the user to configure the disk partitioning +* Prompt the user to setup disk encryption +* Create a file handler instance for the configured disk and the optional disk encryption +* Perform the disk operations (WARNING: this will potentially format the disks and erase all data) +* Install a basic instance of Arch Linux *(base base-devel linux linux-firmware btrfs-progs efibootmgr)* +* Install and configures a bootloader to partition 0 on UEFI. On BIOS, it sets the root to partition 0. +* Install additional packages *(nano, wget, git)* +* Create a new user - boot.mount('/mnt/boot') +> **To create your own ISO with this script in it:** Follow [ArchISO](https://wiki.archlinux.org/index.php/archiso)'s guide on creating your own ISO. -with archinstall.Installer('/mnt') as installation: - if installation.minimal_installation(hostname='minimal-arch'): - installation.add_bootloader() +## Script non-interactive automated installation - installation.add_additional_packages(['nano', 'wget', 'git']) +For an example of a fully scripted, automated installation please refer to the example +[full_automated_installation.py](https://github.com/archlinux/archinstall/blob/master/examples/full_automated_installation.py) - # Optionally, install a profile of choice. - # In this case, we install a minimal profile that is empty - installation.install_profile('minimal') +## Unattended installation based on MAC address - user = User('devel', 'devel', False) - installation.create_users(user) - installation.user_set_pw('root', 'airoot') -``` +Archinstall comes with an [unattended](https://github.com/archlinux/archinstall/blob/master/examples/mac_address_installation.py) +example which will look for a matching profile for the machine it is being run on, based on any local MAC address. +For instance, if the machine the code is executed on has the MAC address `52:54:00:12:34:56` it will look for a profile called +[52-54-00-12-34-56.py](https://github.com/archlinux/archinstall/blob/master/archinstall/default_profiles/tailored.py). +If it's found, the unattended installation will begin and source that profile as its installation procedure. -This installer will perform the following: +# Profiles -* Prompt the user to select a disk and disk-password -* Proceed to wipe the selected disk with a `GPT` partition table on a UEFI system and MBR on a BIOS system. -* Sets up a default 100% used disk with encryption. -* Installs a basic instance of Arch Linux *(base base-devel linux linux-firmware btrfs-progs efibootmgr)* -* Installs and configures a bootloader to partition 0 on uefi. On BIOS, it sets the root to partition 0. -* Install additional packages *(nano, wget, git)* +`archinstall` comes with a set of pre-configured profiles available for selection during the installation process. -> **Creating your own ISO with this script on it:** Follow [ArchISO](https://wiki.archlinux.org/index.php/archiso)'s guide on how to create your own ISO. +- [Desktop](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles/desktops) +- [Server](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles/servers) -## Unattended installation based on MAC address +The profiles' definitions and the packages they will install can be directly viewed in the menu, or +[default profiles](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles) -Archinstall comes with an [unattended](https://github.com/archlinux/archinstall/blob/master/examples/unattended.py) example which will look for a matching profile for the machine it is being run on, based on any local MAC address. -For instance, if the machine that [unattended](https://github.com/archlinux/archinstall/blob/master/examples/unattended.py) is run on has the MAC address `52:54:00:12:34:56` it will look for a profile called [profiles/52-54-00-12-34-56.py](https://github.com/archlinux/archinstall/blob/master/profiles/52-54-00-12-34-56.py). -If it's found, the unattended installation will commence and source that profile as its installation procedure. # Testing ## Using a Live ISO Image -If you want to test a commit, branch or bleeding edge release from the repository using the vanilla Arch Live ISO image, -you can replace the version of archinstall with a new version and run that with the steps described below: +If you want to test a commit, branch, or bleeding edge release from the repository using the standard Arch Linux Live ISO image, +replace the archinstall version with a newer one and execute the subsequent steps defined below. + +*Note: When booting from a live USB, the space on the ramdisk is limited and may not be sufficient to allow +running a re-installation or upgrade of the installer. In case one runs into this issue, any of the following can be used +- Resize the root partition https://wiki.archlinux.org/title/Archiso#Adjusting_the_size_of_the_root_file_system +- The boot parameter `copytoram=y` (https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio-archiso/-/blob/master/docs/README.bootparams#L26) +can be specified which will copy the root filesystem to tmpfs.* 1. You need a working network connection -2. Install the build requirements with `pacman -Sy; pacman -S git python-pip` +2. Install the build requirements with `pacman -Sy; pacman -S git python-pip gcc pkgconf` *(note that this may or may not work depending on your RAM and current state of the squashfs maximum filesystem free space)* -3. Uninstall the previous version of archinstall with `pip uninstall archinstall` +3. Uninstall the previous version of archinstall with `pip uninstall --break-system-packages archinstall` 4. Now clone the latest repository with `git clone https://github.com/archlinux/archinstall` 5. Enter the repository with `cd archinstall` *At this stage, you can choose to check out a feature branch for instance with `git checkout v2.3.1-rc1`* -6. Build the project and install it using `python setup.py install` - *If you get a 'No Module named setuptools' error, run `pacman -S python-setuptools`* - -After this, running archinstall with `python -m archinstall` will run against whatever branch you chose in step 5. +6. To run the source code, there are 2 different options: + - Run a specific branch version from source directly using `python -m archinstall`, in most cases this will work just fine, the + rare case it will not work is if the source has introduced any new dependencies that are not installed yet + - Installing the branch version with `pip install --break-system-packages .` and `archinstall` ## Without a Live ISO Image @@ -178,8 +211,7 @@ To test this without a live ISO, the simplest approach is to use a local image a This can be done by installing `pacman -S arch-install-scripts util-linux` locally and doing the following: # truncate -s 20G testimage.img - # losetup -fP ./testimage.img - # losetup -a | grep "testimage.img" | awk -F ":" '{print $1}' + # losetup --partscan --show --find ./testimage.img # pip install --upgrade archinstall # python -m archinstall --script guided # qemu-system-x86_64 -enable-kvm -machine q35,accel=kvm -device intel-iommu -cpu host -m 4096 -boot order=d -drive file=./testimage.img,format=raw -drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/x64/OVMF_CODE.fd -drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/x64/OVMF_VARS.fd @@ -190,3 +222,44 @@ This will create a *20 GB* `testimage.img` and create a loop device which we can There's also a [Building and Testing](https://github.com/archlinux/archinstall/wiki/Building-and-Testing) guide.<br> It will go through everything from packaging, building and running *(with qemu)* the installer against a dev branch. + + +# FAQ + +## How to dual boot with Windows + +To install Arch Linux alongside an existing Windows installation using `archinstall`, follow these steps: + +1. Ensure some unallocated space is available for the Linux installation after the Windows installation. +2. Boot into the ISO and run `archinstall`. +3. Choose `Disk configuration` -> `Manual partitioning`. +4. Select the disk on which Windows resides. +5. Select `Create a new partition`. +6. Choose a filesystem type. +7. Determine the start and end sectors for the new partition location (values can be suffixed with various units). +8. Assign the mountpoint `/` to the new partition. +9. Assign the `Boot/ESP` partition the mountpoint `/boot` from the partitioning menu. +10. Confirm your settings and exit to the main menu by choosing `Confirm and exit`. +11. Modify any additional settings for your installation as necessary. +12. Start the installation upon completion of setup. + + +# Mission Statement + +Archinstall promises to ship a [guided installer](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) that follows +the [Arch Linux Principles](https://wiki.archlinux.org/index.php/Arch_Linux#Principles) as well as a library to manage services, packages, and other Arch Linux aspects. + +The guided installer ensures a user-friendly experience, offering optional selections throughout the process. Emphasizing its flexible nature, these options are never obligatory. +In addition, the decision to use the guided installer remains entirely with the user, reflecting the Linux philosophy of providing full freedom and flexibility. + +--- + +Archinstall primarily functions as a flexible library for managing services, packages, and other elements within an Arch Linux system. +This core library is the backbone for the guided installer that Archinstall provides. It is also designed to be used by those who wish to script their own custom installations. + +Therefore, Archinstall will try its best to not introduce any breaking changes except for major releases which may break backward compatibility after notifying about such changes. + + +# Contributing + +Please see [CONTRIBUTING.md](https://github.com/archlinux/archinstall/blob/master/CONTRIBUTING.md) |