This change adds the display(1) graphical user interface and desktop environment with basic windowing support and the graphical terminal(1) emulator along with integrations in chkblayout(1), chvideomode(1), sysinstall(8), sysupgrade(8), as well as the games and ports. Adopt the Aurora procedural wallpaper in display(1) and login(8). Remove the obsolete dispd. Juhani contributed keyboard and video mode APIs to the display protocol and other miscellaneous changes. dzwdz contributed the initial functioning window buttons, improved title bar, window tiling, and minor bug fixes Co-authored-by: Juhani Krekelä <juhani@krekelä.fi> Co-authored-by: dzwdz <kg67199@gmail.com>
573 lines
20 KiB
Groff
573 lines
20 KiB
Groff
.Dd December 25, 2015
|
|
.Dt INSTALLATION 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm installation
|
|
.Nd operating system installation instructions
|
|
.Sh DESCRIPTION
|
|
This document describes how to install Sortix on a computer from a cdrom
|
|
release.
|
|
Please read it through carefully before beginning the installation so you know
|
|
what to expect and things you need to keep in mind.
|
|
The
|
|
.Xr upgrade 7
|
|
manual page covers upgrading an existing installation.
|
|
.Ss Prerequisites
|
|
.Bl -bullet -compact
|
|
.It
|
|
A
|
|
.Pa sortix-x.y-arch.iso
|
|
release for your architecture.
|
|
.It
|
|
A cdrom onto which the release has been burned, or USB portable storage onto
|
|
which the release has been placed at the first byte and onwards.
|
|
.It
|
|
A computer meeting the system requirements.
|
|
.El
|
|
.Ss System Requirements
|
|
.Bl -bullet -compact
|
|
.It
|
|
32-bit x86 CPU (i686 release) or 64-bit x86 CPU (x86_64 release).
|
|
.It
|
|
1 GiB RAM (recommended) to run iso live environment (including installer) with
|
|
all ports loaded, or significantly less if unimportant ports are not loaded.
|
|
An installation on a harddisk will require very little RAM to run after
|
|
installation.
|
|
.It
|
|
ATA or AHCI harddisk with at least 1 GiB of unpartitioned space.
|
|
.It
|
|
BIOS firmware, or UEFI firmware in legacy mode.
|
|
.It
|
|
PS/2 keyboard/mouse firmware emulation to use those devices.
|
|
.It
|
|
If you wish to dual boot, you need an existing operating system with a multiboot
|
|
compliant bootloader such as GRUB.
|
|
.El
|
|
.Ss Preparation
|
|
Read this document through before beginning the installation.
|
|
The installation process is designed to be reasonable, but you need to patient
|
|
and in an emotionally stable place.
|
|
It is important you understand the current limitations of the system and
|
|
carefully consider whether you want to go through with the installation at this
|
|
time.
|
|
.Pp
|
|
Before installing any operating system, be sure to have backed up local data in
|
|
the event something goes wrong.
|
|
This operating system comes without any warranty at all (see the license).
|
|
.Pp
|
|
Consider the partitioning scheme and whether you wish to dual boot.
|
|
Consult the partitioning instructions below.
|
|
If dual-booting and there isn't enough unpartitioned space, use the native
|
|
partition editor of the existing operating system to shrink its installation.
|
|
.Pp
|
|
Determine how the target machine will boot the release.
|
|
If the firmware supports usb-iso hybrid images, you can use
|
|
.Xr rw 1
|
|
or
|
|
.Xr dd 1
|
|
to copy the release physically onto a USB portable storage device.
|
|
If the target machine has a cdrom drive, you can burn the release to a cdrom.
|
|
Insert the installation medium in the computer and power it on.
|
|
If needed, change the boot order in the firmware to prefer the installation
|
|
medium over any existing operating system installations.
|
|
.Pp
|
|
After the installation is complete, remove the installation medium and restore
|
|
the firmware boot order to prioritize the local harddisk.
|
|
Then power the computer on normally to run the new operating system.
|
|
.Ss Release .iso Modification
|
|
Optionally, you might want to modify a release .iso to meet your custom needs
|
|
per the instructions in
|
|
.Xr release-iso-modification 7 .
|
|
.Pp
|
|
If you want to ssh into your installation, it's recommended to amend the
|
|
installation .iso with your public key, pregenerate the server keys and obtain
|
|
fingerprints, and seed randomness using this procedure.
|
|
.Pp
|
|
The release modification procedure lets you customize aspects such as the
|
|
default bootloader menu option and timeout, the default hostname, the default
|
|
keyboard layout, the default graphics resolution, adding files of your choice to
|
|
the live environment, control which drivers are loaded by default, control which
|
|
live environment daemons are started by default, deploy ssh keys so secure shell
|
|
connections are trusted on the first connection, configure automatic
|
|
installation and upgrading, and so on.
|
|
.Pp
|
|
Warning: The live environment does not come with any random entropy and entropy
|
|
gathering is not yet implemented.
|
|
To keep your system secure, it is recommended to use the release modification
|
|
procedure to add a
|
|
.Pa /boot/random.seed
|
|
file to the release .iso in order to securely seed the cryptographically secure
|
|
pseudorandom number generator.
|
|
.Ss Qemu
|
|
Virtual machines are a well-supported installation target.
|
|
For instance, to prepare a 1 GiB harddisk and install the operating system onto
|
|
it, run something
|
|
like:
|
|
.Bd -literal
|
|
qemu-img create sortix.raw 1G
|
|
qemu-system-x86_64 -enable-kvm -m 1024 -vga std -cdrom sortix.iso \\
|
|
-drive file=sortix.raw,format=raw
|
|
.Ed
|
|
.Pp
|
|
After the installation is complete, power off the computer and remove the
|
|
.Ar -cdrom
|
|
.Pa sortix.iso
|
|
option.
|
|
.Ss Bootloader Menu
|
|
Booting the release will present you with a GRUB bootloader menu.
|
|
You have three primary options:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Running a fully-featured temporary live environment.
|
|
.It
|
|
Running the operating system installer
|
|
.Xr ( sysinstall 8 ) .
|
|
.It
|
|
Upgrading an existing installation to this release
|
|
.Xr ( sysupgrade 8 ) .
|
|
.El
|
|
.Pp
|
|
Each of these options are a live environment running exclusively in RAM.
|
|
The difference is only what program is run after the system has booted.
|
|
The bootloader will load the whole operating system and ports into memory from
|
|
the installation medium.
|
|
This may take a moment.
|
|
You need enough memory to store the whole system and the runtime usage.
|
|
If the system memory is really insufficient, then the bootloader may have
|
|
strange behavior, take a really long time to load, or not complete the boot at
|
|
all.
|
|
.Ss Bootloader Advanced Options
|
|
The bootloader advanced options menu lets you customize the live environment by
|
|
making one-time adjustments to the boot process.
|
|
These decisions will not carry over to the final installed system, which you
|
|
instead will need to configure to have the same effects.
|
|
.Pp
|
|
You can configure which ports gets loaded using the bootloader menu.
|
|
The base system is rather lean and can be made quite small.
|
|
You need some ports to complete an installation.
|
|
Only the selected ports are loaded into the live environment and installed onto
|
|
the new installation.
|
|
If upgrading an existing installation, then any ports not loaded will be removed
|
|
from the installation being upgraded.
|
|
.Pp
|
|
Ports can additionally be loaded as binary packages in the
|
|
.Pa /repository
|
|
directory by navigating to the advanced menu and then the select binary packages
|
|
submenu and then selecting which ports.
|
|
.Pp
|
|
The
|
|
.Xr display 1
|
|
graphical user interface and desktop environment can be disabled by navigating
|
|
to the advanced menu and selecting
|
|
.Sy Disable GUI ,
|
|
which will instead boot to a plain
|
|
.Pa /dev/tty1
|
|
terminal.
|
|
.Pp
|
|
The network drivers can be disabled by navigating to the advanced menu and
|
|
selecting
|
|
.Sy Disable network drivers .
|
|
It can be useful to disable the network drivers if it's undesirable to put the
|
|
system on the network for security reasons.
|
|
You can disable network drivers by default by editing the bootloader
|
|
configuration as described below after completing the installation.
|
|
.Pp
|
|
By default
|
|
.Xr dhclient 8
|
|
will automatically configure
|
|
.Xr ether 4
|
|
network interfaces with DHCP and bring up network connectivity.
|
|
The DHCP client can be disabled by navigating to the advanced menu and selecting
|
|
.Sy Disable DHCP client ,
|
|
which is useful if you want to manually configure the network or not expose the
|
|
system until you are ready.
|
|
.Ss Installer
|
|
This guide assumes you selected the operating system installation option in the
|
|
bootloader.
|
|
If not, you can run the installer by running the
|
|
.Xr sysinstall 8
|
|
command.
|
|
.Pp
|
|
You will boot into the
|
|
.Xr display 1
|
|
graphical user interface and desktop environment by default.
|
|
A single
|
|
.Xr terminal 1
|
|
window will open by default.
|
|
More terminals can be opened by pressing Control + Alt + T.
|
|
See
|
|
.Xr display 1
|
|
for the available shortcuts.
|
|
.Pp
|
|
The installer is an interactive command line program that asks you questions and
|
|
you answer them.
|
|
It provides useful information you shouldn't accidentally overlook.
|
|
Before answering any question, read all output since your last answer.
|
|
.Pp
|
|
You should have this installation guide ready at all times.
|
|
You can view this
|
|
.Xr installation 7
|
|
page during the installation by answering
|
|
.Sy '!man'
|
|
to any regular prompt (excluding password prompts).
|
|
Likewise you can answer
|
|
.Sy '!'
|
|
to get an interactive shell.
|
|
Upon completion, you will be asked the question again.
|
|
.Ss Keyboard Layout
|
|
You need to choose the applicable keyboard layout.
|
|
By default, a standard US keyboard layout is used.
|
|
You can view a list of keyboard layouts if you wish.
|
|
This layout is then loaded and the preference will be stored in
|
|
.Xr kblayout 5 .
|
|
.Ss Display Resolution
|
|
If a driver exists for your graphics card, then you will be asked for your
|
|
preferred display resolution by
|
|
.Xr chvideomode 1 .
|
|
The display will then use this resolution and your preference will be stored in
|
|
.Xr videomode 5 .
|
|
.Ss Bootloader
|
|
The
|
|
.Xr kernel 7
|
|
is a multiboot compatible binary that can be loaded by any multiboot
|
|
specification compatible bootloader such as GRUB.
|
|
You need to use such a bootloader to boot the operating system.
|
|
You will be offered the choice of installing GRUB as the bootloader.
|
|
Note however that this GRUB is not able to detect other operating systems and
|
|
you will have to configure it manually if you wish to use it in a dual boot
|
|
scheme.
|
|
The answer will default to yes if no existing partitions are found, or if an
|
|
existing Sortix installation is found that uses the provided bootloader; and
|
|
will otherwise default to no.
|
|
.Pp
|
|
The bootloader will be installed on the boot harddisk, which is the harddisk
|
|
containing the
|
|
.Pa /boot
|
|
partition if any, and otherwise the harddisk containing the root filesystem.
|
|
.Pp
|
|
Single-boot configurations should use the offered bootloader.
|
|
Dual-boot configurations should refuse it and arrange for bootloading by other
|
|
means.
|
|
The installer will generate
|
|
.Pa /etc/grub.d/10_sortix.cache
|
|
which is a fragment of GRUB configuration that offers the menu option of running
|
|
Sortix.
|
|
You can splice that into
|
|
.Pa /etc/grub.d/40_custom
|
|
of an existing GRUB installation and run
|
|
.Xr update-grub 8
|
|
to add it as a boot option.
|
|
.Pp
|
|
If you accept the bootloader, you will be asked if you wish to password protect
|
|
the bootloader.
|
|
If you don't, anyone able to use the keyboard during system bootloading will be
|
|
trivially able to gain root access using the bootloader command line.
|
|
If you use this, you should also password protect the firmware and prohibit it
|
|
from booting from anything but the harddisk.
|
|
An attacker will then need to tamper with the computer itself physically.
|
|
The password will be hashed and stored in
|
|
.Xr grubpw 5
|
|
and is inserted into the GRUB configuration when
|
|
.Xr update-grub 8
|
|
is run.
|
|
.Ss Partitioning
|
|
You will now need to set up a partition for the root filesystem and other
|
|
filesystems you wish to use.
|
|
The installer will give you instructions and run the
|
|
.Xr disked 8
|
|
partitioning program.
|
|
You can view its man page by typing
|
|
.Sy man
|
|
and you can view this man page by typing
|
|
.Sy man 7 installation .
|
|
.Pp
|
|
.Nm disked
|
|
defaults to the first detected harddisk as the current harddisk.
|
|
You can switch to another harddisk using the
|
|
.Sy device Ar device-name
|
|
command.
|
|
You can view all devices with the
|
|
.Sy devices
|
|
command.
|
|
.Pp
|
|
If the current device does not already have a partition table, you can create a
|
|
.Xr mbr 7
|
|
or
|
|
.Xr gpt 7
|
|
partition table using the
|
|
.Sy mktable
|
|
command.
|
|
.Xr gpt 7
|
|
is the preferred choice for new partition tables as
|
|
.Xr mbr 7 has unfortunate limitations.
|
|
If you are dissatisfied with the current partition table, you can use
|
|
the
|
|
.Sy rmtable
|
|
command which will destroy the partition table and effectively delete all data
|
|
on the harddisk.
|
|
.Pp
|
|
The
|
|
.Sy ls
|
|
command lists all partitions and unused space on the current device.
|
|
The
|
|
.Sy mkpart
|
|
command creates a partition.
|
|
You will be asked interactive questions to determine its location.
|
|
You will be asked if you wish to format a filesystem.
|
|
.Nm ext2
|
|
is the native filesystem.
|
|
If applicable, you will be asked if you wish to create a mountpoint for it in
|
|
.Xr fstab 5 .
|
|
The
|
|
.Sy rmpart Ar partition-number
|
|
command removes a partition table entry and effectively deletes all data on the
|
|
partition.
|
|
.Pp
|
|
If you accepted the included bootloader, it will be installed on the boot
|
|
harddisk, which is the harddisk containing the
|
|
.Pa /boot
|
|
partition if any, and otherwise the harddisk containing the root filesystem.
|
|
If the boot harddisk uses the
|
|
.Xr gpt 7
|
|
partitioning scheme, then you must create a
|
|
.Sy biosboot
|
|
partition on the boot harddisk which is where the bootloader will be installed.
|
|
It should be at the start of the boot harddisk and a size of 1 MiB will be more
|
|
than sufficient.
|
|
.Pp
|
|
You need to make a partition containing the root filesystem mounted at
|
|
.Pa / .
|
|
A size of 1 GiB will be comfortable for the base system and ports and basic
|
|
usage.
|
|
There is no inherent need for a
|
|
.Pa /boot
|
|
or a
|
|
.Pa /home
|
|
partition, so you are encouraged to make the root filesystem as large as you
|
|
wish.
|
|
Operating systems upgrades will preserve the root filesystem and the installer
|
|
handles installing on top of an existing installation and preserves user files
|
|
and local configuration.
|
|
.Pp
|
|
Type
|
|
.Sy exit
|
|
when you are done to continue the installation.
|
|
If the installer detects a problem with your partitioning, it will offer to run
|
|
.Xr disked 8
|
|
again.
|
|
.Ss Installation
|
|
The installer will show its installation intentions and ask you to confirm the
|
|
installation.
|
|
If you answer yes, then the installation will begin.
|
|
.Pp
|
|
The installer will copy the live environment into the target root filesystem
|
|
according to the file lists in
|
|
.Pa /tix/manifest
|
|
and create configuration files matching your earlier choices.
|
|
It will write 256 bytes of randomness to
|
|
.Pa /boot/random.seed .
|
|
It will generate an initrd that locates and boots the root filesystem.
|
|
It will install the bootloader if desired.
|
|
The installation will take a moment.
|
|
.Ss Configuration
|
|
After the installation is complete, a bare system is installed but it lacks
|
|
crucial configuration files and it will refuse to start when booted.
|
|
.Ss Hostname
|
|
You will be asked for the hostname of the new system which be stored in
|
|
.Xr hostname 5 .
|
|
This question is skipped if the file already exits.
|
|
.Ss Root
|
|
You will be asked for the root password.
|
|
A root account is made in
|
|
.Xr passwd 5
|
|
and
|
|
.Xr group 5 .
|
|
This question is skipped if the root account already exists.
|
|
If the live environment's root user has ssh keys and configuration, you will be
|
|
asked whether you'd like to copy the files to the new installation.
|
|
.Ss Users
|
|
You will be asked in a loop if you wish to make another user.
|
|
Answer
|
|
.Sy no
|
|
when you are done.
|
|
Otherwise enter the name of the new account.
|
|
If you wish to create an account by the name of
|
|
.Li no
|
|
then simply add a space in front as leading spaces are trimmed.
|
|
.Pp
|
|
You will then be asked for the full name and the password for the new user.
|
|
A user directory will be made in
|
|
.Pa /home .
|
|
The new user is added to
|
|
.Xr passwd 5
|
|
and
|
|
.Xr group 5 .
|
|
.Pp
|
|
Please note that Sortix is not currently secure as a multi-user system and
|
|
filesystem permissions are not enforced.
|
|
.Ss Graphical User Interface
|
|
You will be asked if you want to enable the graphical user interface.
|
|
If you answer yes, then the system-wide default
|
|
.Xr session 5
|
|
is configured to run
|
|
.Xr display 1
|
|
upon login.
|
|
Otherwise the user's preferred shell will be run upon login.
|
|
.Ss Network Time
|
|
You will be asked if you want to enable the Network Time Protocol client
|
|
.Xr ntpd 8 ,
|
|
which will automatically synchronize the current time with the internet.
|
|
Although it's recommended to use network time to avoid clock drift, it does come
|
|
with potential privacy implications.
|
|
.Pp
|
|
Privacy notice: If enabled, the default configuration will obtain time from
|
|
various internet servers and the installer will inform you which ones they are.
|
|
You are encouraged to answer
|
|
.Sy man
|
|
to read the
|
|
.Xr ntpd.conf 5
|
|
manual and then answer
|
|
.Sy edit
|
|
to edit the configuration with your preferences.
|
|
.Ss SSH Server
|
|
You will be asked if you want to enable a
|
|
.Xr sshd 8
|
|
server for remotely logging into this machine over a secure cryptographic
|
|
channel.
|
|
Answer no if in doubt as anyone who obtains your credentials will be able to
|
|
connect to your computer and log in as you.
|
|
Password authentication is disabled by default as public key cryptography should
|
|
be used for security, but if you have a very strong password, you could enable
|
|
it when asked.
|
|
It's recommended to securely bootstrap ssh authentication using the
|
|
.Xr release-iso-modification 7
|
|
procedure to amend the installation medium with your public key, pregenerated
|
|
server private keys, and a random seed.
|
|
You are using a bad workflow if you encounter a ssh server fingerprint check.
|
|
If the installer environment contains a
|
|
.Xr sshd_config
|
|
or private sshd keys, then you will be asked if you want to copy the files into
|
|
the new installation.
|
|
.Ss Completion
|
|
This will complete the operating system installation.
|
|
Upon reboot, the new system will start normally.
|
|
After powering off your system, you need to remove the installation medium and
|
|
(if applicable) restore boot priorities in your firmware.
|
|
If you did not accept the bootloader, you will need to manually configure a
|
|
bootloader to boot the new operating system.
|
|
.Pp
|
|
You will be given the choice of directly booting into the new system without a
|
|
reboot, powering off the system, rebooting the system, halting the system, or
|
|
chrooting into the new system.
|
|
All of these options (except the
|
|
.Xr chroot 2 )
|
|
will destroy the live environment and all files within it will be lost.
|
|
.Pp
|
|
This is a last chance to make modifications before the new system boots for the
|
|
first time.
|
|
If you want to make final modifications to the system (examples are below), you
|
|
can answer
|
|
.Sy '!'
|
|
to escape to a shell in the live environment inside the subdirectory where the
|
|
new system is mounted.
|
|
You can then run
|
|
.Sy "chroot -d ."
|
|
to enter a shell within the new installation.
|
|
.Pp
|
|
Upon boot of the new system it will be configured in multi-user mode and you
|
|
will be presented with a login screen.
|
|
Authenticate as one of the local users and you will be given a shell.
|
|
.Pp
|
|
To power off the computer login as user
|
|
.Sy poweroff
|
|
or run
|
|
.Xr poweroff 8
|
|
after logging in.
|
|
To reboot the computer login as user
|
|
.Sy reboot
|
|
or run
|
|
.Xr reboot 8
|
|
after logging in.
|
|
.Pp
|
|
The
|
|
.Xr user-guide 7
|
|
manual page is a basic overview of the system for new users.
|
|
.Pp
|
|
Congratulations on your new Sortix system.
|
|
.Ss Disabling Networking by Default
|
|
To disable networking drivers by default, edit the bootloader configuration to
|
|
pass the
|
|
.Fl \-disable-network-drivers
|
|
option by default on the
|
|
.Xr kernel 7
|
|
command line.
|
|
.Pp
|
|
If you are at the final stage of installation, you can answer
|
|
.Sy '!'
|
|
to get a shell in the live environment and then run
|
|
.Sy "chroot -d ."
|
|
to enter a shell inside the new installation.
|
|
.Pp
|
|
For instance, if GRUB is used the bootloader, networking can be disabled by
|
|
default by done by editing
|
|
.Pa /etc/grub.d/10_sortix
|
|
of the new installation.
|
|
.Xr editor 1
|
|
or any editor can be used to edit the file.
|
|
Change the line from
|
|
.Bd -literal
|
|
multiboot $BOOT_REL/sortix.bin
|
|
.Ed
|
|
.Pp
|
|
to instead be
|
|
.Bd -literal
|
|
multiboot $BOOT_REL/sortix.bin --disable-network-drivers
|
|
.Ed
|
|
.Pp
|
|
If the included GRUB bootloader is used, after making the above edit, run
|
|
.Xr update-grub 8
|
|
within the new installation to regenerate the bootloader configuration.
|
|
Note that
|
|
.Pa /etc/grub.d/10_sortix
|
|
is part of the GRUB package and local changes will be undone when the GRUB
|
|
package is updated or reinstalled, in which case you must make this change again
|
|
and run
|
|
.Xr update-grub 8
|
|
again.
|
|
.Pp
|
|
If the included GRUB bootloader is not used, but instead the
|
|
.Pa /etc/grub.d/10_sortix.cache
|
|
fragment is spliced into another GRUB installation, make the above change and
|
|
then run the
|
|
.Pa /etc/grub.d/10_sortix
|
|
command and use the freshly regenerated
|
|
.Pa /etc/grub.d/10_sortix.cache
|
|
fragment instead.
|
|
.Sh SEE ALSO
|
|
.Xr chkblayout 1 ,
|
|
.Xr chvideomode 1 ,
|
|
.Xr display 1 ,
|
|
.Xr man 1 ,
|
|
.Xr fstab 5 ,
|
|
.Xr group 5 ,
|
|
.Xr grubpw 5 ,
|
|
.Xr kblayout 5 ,
|
|
.Xr passwd 5 ,
|
|
.Xr videomode 5 ,
|
|
.Xr development 7 ,
|
|
.Xr gpt 7 ,
|
|
.Xr initrd 7 ,
|
|
.Xr kernel 7 ,
|
|
.Xr mbr 7 ,
|
|
.Xr release-iso-modification 7 ,
|
|
.Xr upgrade 7 ,
|
|
.Xr user-guide 7 ,
|
|
.Xr disked 8 ,
|
|
.Xr fsck 8 ,
|
|
.Xr init 8 ,
|
|
.Xr sysinstall 8 ,
|
|
.Xr sysupgrade 8 ,
|
|
.Xr update-grub 8 ,
|
|
.Xr update-initrd 8
|