From 929f6941790eaa321f7687347a4b02ac07c4e648 Mon Sep 17 00:00:00 2001 From: Cem Keylan Date: Sun, 28 Aug 2022 11:16:20 +0300 Subject: docs: update --- carbslinux.texi | 113 ++++++++++++++++++++++++++++++++++++++++++-------------- carbslinux.txt | 83 ++++++++++++++++++++++++++++++++++++----- install.org | 46 +++++++++++++++++++---- install.txt | 53 ++++++++++++++++++++++---- 4 files changed, 242 insertions(+), 53 deletions(-) diff --git a/carbslinux.texi b/carbslinux.texi index 6c98bc5..de18f2f 100644 --- a/carbslinux.texi +++ b/carbslinux.texi @@ -94,6 +94,7 @@ System Configuration * Configuring hostname:: Setting up system hostname (recommended) * Hosts file:: Setting up hosts file for networking (optional) +* Creating a user:: Adding a user to your new system Kernel @@ -300,7 +301,7 @@ mkdir -p $HOME/repos @enumerate @item -Obtaining from git +@anchor{Obtaining from git}Obtaining from git Carbs Linux git repositories can be found both from the main server and GitHub @@ -318,7 +319,7 @@ git clone git://git.carbslinux.org/repository $HOME/repos/carbs @end example @item -Obtaining from rsync +@anchor{Obtaining from rsync}Obtaining from rsync Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In @@ -329,7 +330,7 @@ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs @end example @item -Making the package manager use the repositories +@anchor{Making the package manager use the repositories}Making the package manager use the repositories In your shell's configuration file, or in your @samp{~/.profile} file, add the @@ -452,6 +453,7 @@ system to your liking. @menu * Configuring hostname:: Setting up system hostname (recommended) * Hosts file:: Setting up hosts file for networking (optional) +* Creating a user:: Adding a user to your new system @end menu @node Configuring hostname @@ -476,6 +478,35 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost @end example +@node Creating a user +@subsection Creating a user + +Creating a new user is not strictly necessary, but it is highly recommended. +Especially for building packages, it is the safest option to create an +unprivileged user and using @samp{doas} for doing operations that require @samp{root} +privileges. The code block below describes how to create a user (named @samp{foo}), +add them to the wheel group, and to give doas permissions to the wheel group + +@example +# Create the new user +adduser foo + +# Add the user to the wheel group +addgroup foo wheel + +# Give root permission to the wheel group using doas +echo permit persist :wheel >> /etc/doas.conf +@end example + +You are also advised to take a look at the doas configuration file and the +manual page of doas. + +After you are finished you can switch to the new user by running + +@example +su foo +@end example + @node Kernel @section Kernel @@ -494,17 +525,21 @@ need to reconfigure for your specific setup if you want to make use of it. You can visit the @uref{https://kernel.org} website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) versions are -supported. +supported. Note that kernel releases are quite rapid, and the version below is +likely outdated, so don't run it verbatim. @example # Download the kernel and extract it -wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz -tar xf linux-5.9.1.tar.xz +wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.19.4.tar.xz +tar xJf linux-5.19.4.tar.xz # Change directory into the kernel sources -cd linux-5.9.1 +cd linux-5.19.4 @end example +@strong{NOTE:} If you want to validate the kernel signature, install the @samp{gnupg2} +package, and follow the instructions provided at @uref{https://kernel.org/category/signatures.html}. + @node Kernel dependencies @subsection Kernel dependencies @@ -565,7 +600,7 @@ without UEFI support (or you really want to use BIOS for a reason). @enumerate @item -GRUB BIOS installation +@anchor{GRUB BIOS installation}GRUB BIOS installation @example @@ -575,7 +610,7 @@ grub-mkconfig -o /boot/grub/grub.cfg @end example @item -GRUB UEFI installation +@anchor{GRUB UEFI installation}GRUB UEFI installation @example @@ -684,7 +719,7 @@ Init Hooks @enumerate @item -Kernel Command Line +@anchor{Kernel Command Line}Kernel Command Line On GRUB, you can edit the kernel command line parameters, which will be parsed @@ -710,7 +745,7 @@ Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quie used by the init system to change the behaviour of the startup. @item -@samp{/etc/init/rc.conf} file +@anchor{@samp{/etc/init/rcconf} file}@samp{/etc/init/rc.conf} file However, the kernel command line isn't the only place to set your boot @@ -719,7 +754,7 @@ kernel command line always gets the priority for these variables since they can be set just before boot. @item -Init Hooks +@anchor{Init Hooks}Init Hooks Init hooks are for custom personal commands that the user may want to add to @@ -771,7 +806,7 @@ cpt a runit /usr/bin/reboot @enumerate @item -Rebooting after changing init +@anchor{Rebooting after changing init}Rebooting after changing init After switching init systems, your running init system may not accept the @@ -812,7 +847,7 @@ section. @enumerate @item -Enabling the Wayland repository +@anchor{Enabling the Wayland repository}Enabling the Wayland repository The @samp{wayland} repository requires packages from @samp{xorg} and @samp{extra} repositories. @@ -837,7 +872,7 @@ cpt-build wayland wayland-protocols @end example @item -Switching from Xorg +@anchor{Switching from Xorg}Switching from Xorg If you are already an Xorg user, you will need to rebuild some packages so that @@ -858,7 +893,7 @@ webkit2gtk @end itemize @item -@strong{TODO} Installing a Compositor +@anchor{Installing a Compositor}@strong{TODO} Installing a Compositor The @samp{wayland} repository currently only contains @samp{sway} as a Wayland compositor, @@ -1007,7 +1042,10 @@ taken literally, they are meant as examples. @enumerate @item -Make [@anchor{2210}2210] +@anchor{Make [2210]}Make [2210] + + +@anchor{2210} @example @@ -1018,7 +1056,10 @@ make DESTDIR="$1" PREFIX=/usr install @end example @item -Configure/Make [@anchor{2211}2211] +@anchor{Configure/Make [2211]}Configure/Make [2211] + + +@anchor{2211} @example @@ -1034,7 +1075,10 @@ make DESTDIR="$1" install @end example @item -Autoconf/Automake [@anchor{2212}2212] +@anchor{Autoconf/Automake [2212]}Autoconf/Automake [2212] + + +@anchor{2212} @xref{2020} @@ -1054,16 +1098,22 @@ make DESTDIR="$1" install @end example @item -Meson [@anchor{2220}2220] +@anchor{Meson [2220]}Meson [2220] + + +@anchor{2220} +The distribution provides a @samp{cl-meson} wrapper script which sets some common +options like installation directories, disables downloading subprojects among +other things. This is the preferred method for packages. + @example #!/bin/sh -e export DESTDIR=$1 -meson \ - --prefix=/usr \ +cl-meson \ -Doption=false \ -Doption2=true \ . output @@ -1073,7 +1123,10 @@ ninja -C output install @end example @item -Cmake [@anchor{2230}2230] +@anchor{Cmake [2230]}Cmake [2230] + + +@anchor{2230} @example @@ -1091,7 +1144,10 @@ cmake --install build @end example @item -Go [@anchor{2240}2240] +@anchor{Go [2240]}Go [2240] + + +@anchor{2240} @example @@ -1106,7 +1162,10 @@ install -Dm755 program "$1/usr/bin/program" @end example @item -Python [@anchor{2241}2241] +@anchor{Python [2241]}Python [2241] + + +@anchor{2241} @example @@ -1181,7 +1240,7 @@ options that are just as useful as @samp{git send-email}. @enumerate @item -@samp{git-send-email} with msmtp +@anchor{@samp{git-send-email} with msmtp}@samp{git-send-email} with msmtp By default, @samp{git-send-email} uses a Perl SMTP client, but without using it this @@ -1199,7 +1258,7 @@ To your @samp{~/.gitconfig}, add the following section: @end example @item -@samp{git-imap-send} +@anchor{@samp{git-imap-send}}@samp{git-imap-send} The @samp{git imap-send} command reads patches in mbox format, and uploads it to your diff --git a/carbslinux.txt b/carbslinux.txt index f51b3a1..362d0cf 100644 --- a/carbslinux.txt +++ b/carbslinux.txt @@ -1,9 +1,9 @@ - _________________________ + _________________________ - CARBS LINUX USER MANUAL + CARBS LINUX USER MANUAL - Cem Keylan - _________________________ + Cem Keylan + _________________________ Table of Contents @@ -24,6 +24,7 @@ _________________ .. 3. System Configuration ..... 1. Configuring hostname ..... 2. Hosts file +..... 3. Creating a user .. 4. Kernel ..... 1. Obtaining the kernel sources ..... 2. Kernel dependencies @@ -101,6 +102,7 @@ with the info reader. It is divided into sections and easier to read. .. 3. System Configuration ..... 1. Configuring hostname ..... 2. Hosts file + ..... 3. Creating a user .. 4. Kernel ..... 1. Obtaining the kernel sources ..... 2. Kernel dependencies @@ -397,6 +399,37 @@ with the info reader. It is divided into sections and easier to read. `---- +2.3.3 Creating a user +--------------------- + + Creating a new user is not strictly necessary, but it is highly + recommended. Especially for building packages, it is the safest + option to create an unprivileged user and using `doas' for doing + operations that require `root' privileges. The code block below + describes how to create a user (named `foo'), add them to the wheel + group, and to give doas permissions to the wheel group + + ,---- + | # Create the new user + | adduser foo + | + | # Add the user to the wheel group + | addgroup foo wheel + | + | # Give root permission to the wheel group using doas + | echo permit persist :wheel >> /etc/doas.conf + `---- + + You are also advised to take a look at the doas configuration file and + the manual page of doas. + + After you are finished you can switch to the new user by running + + ,---- + | su foo + `---- + + 2.4 Kernel ~~~~~~~~~~ @@ -414,17 +447,22 @@ with the info reader. It is divided into sections and easier to read. You can visit the website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) - versions are supported. + versions are supported. Note that kernel releases are quite rapid, and + the version below is likely outdated, so don't run it verbatim. ,---- | # Download the kernel and extract it - | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz - | tar xf linux-5.9.1.tar.xz + | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.19.4.tar.xz + | tar xJf linux-5.19.4.tar.xz | | # Change directory into the kernel sources - | cd linux-5.9.1 + | cd linux-5.19.4 `---- + *NOTE:* If you want to validate the kernel signature, install the + `gnupg2' package, and follow the instructions provided at + . + 2.4.2 Kernel dependencies ------------------------- @@ -874,6 +912,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.1 Make [2210] + + + ,---- | #!/bin/sh -e | @@ -884,6 +925,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.2 Configure/Make [2211] + + + ,---- | #!/bin/sh -e | @@ -899,6 +943,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.3 Autoconf/Automake [2212] + + + ,---- | #!/bin/sh -e | @@ -916,13 +963,20 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.4 Meson [2220] + + + + The distribution provides a `cl-meson' wrapper script which sets some + common options like installation directories, disables downloading + subprojects among other things. This is the preferred method for + packages. + ,---- | #!/bin/sh -e | | export DESTDIR=$1 | - | meson \ - | --prefix=/usr \ + | cl-meson \ | -Doption=false \ | -Doption2=true \ | . output @@ -934,6 +988,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.5 Cmake [2230] + + + ,---- | #!/bin/sh -e | @@ -951,6 +1008,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.6 Go [2240] + + + ,---- | #!/bin/sh -e | @@ -965,6 +1025,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.7 Python [2241] + + + ,---- | #!/bin/sh -e | diff --git a/install.org b/install.org index c0b1f0a..88fb7bf 100644 --- a/install.org +++ b/install.org @@ -1,6 +1,6 @@ -# Created 2021-12-02 Thu 07:15 -#+TITLE: Carbs Linux Installation Guide -#+AUTHOR: Cem Keylan +# Created 2022-08-28 Sun 11:16 +#+title: Carbs Linux Installation Guide +#+author: Cem Keylan These are the step-by-step instructions for installing Carbs Linux. It can be acquired as plain-text to be viewed offline with a pager from [[https://carbslinux.org/install.txt]]. @@ -78,7 +78,6 @@ If everything went alright, this should output: #+end_example - ** Extracting the tarball You will need to extract the tarball to your desired location. For partitioning, you can follow [[https://wiki.archlinux.org/index.php/Partitioning][this guide]]. This will assume that you will be mounting your root @@ -237,6 +236,33 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost #+end_example +** Creating a user +Creating a new user is not strictly necessary, but it is highly recommended. +Especially for building packages, it is the safest option to create an +unprivileged user and using =doas= for doing operations that require =root= +privileges. The code block below describes how to create a user (named =foo=), +add them to the wheel group, and to give doas permissions to the wheel group + +#+begin_src sh + # Create the new user + adduser foo + + # Add the user to the wheel group + addgroup foo wheel + + # Give root permission to the wheel group using doas + echo permit persist :wheel >> /etc/doas.conf +#+end_src + +You are also advised to take a look at the doas configuration file and the +manual page of doas. + +After you are finished you can switch to the new user by running + +#+begin_src sh + su foo +#+end_src + * Kernel Kernel isn't managed under the main repositories, even though you could package one for your personal use. Here is an [[https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux][example kernel package]], which you will @@ -245,17 +271,21 @@ need to reconfigure for your specific setup if you want to make use of it. ** Obtaining the kernel sources You can visit the [[https://kernel.org]] website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) versions are -supported. +supported. Note that kernel releases are quite rapid, and the version below is +likely outdated, so don't run it verbatim. #+begin_src sh # Download the kernel and extract it - wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz - tar xf linux-5.9.1.tar.xz + wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.19.4.tar.xz + tar xJf linux-5.19.4.tar.xz # Change directory into the kernel sources - cd linux-5.9.1 + cd linux-5.19.4 #+end_src +*NOTE:* If you want to validate the kernel signature, install the =gnupg2= +package, and follow the instructions provided at [[https://kernel.org/category/signatures.html]]. + ** Kernel dependencies In order to compile the kernel you will need to install some dependencies. You will need =libelf=, and =bison= to compile the kernel. If you want to configure diff --git a/install.txt b/install.txt index 0704b7b..fdc90fd 100644 --- a/install.txt +++ b/install.txt @@ -1,9 +1,9 @@ - ________________________________ + ________________________________ - CARBS LINUX INSTALLATION GUIDE + CARBS LINUX INSTALLATION GUIDE - Cem Keylan - ________________________________ + Cem Keylan + ________________________________ These are the step-by-step instructions for installing Carbs Linux. It @@ -30,6 +30,7 @@ can be acquired as plain-text to be viewed offline with a pager from 3. System Configuration .. 1. Configuring hostname .. 2. Hosts file +.. 3. Creating a user 4. Kernel .. 1. Obtaining the kernel sources .. 2. Kernel dependencies @@ -331,6 +332,37 @@ can be acquired as plain-text to be viewed offline with a pager from `---- +3.3 Creating a user +~~~~~~~~~~~~~~~~~~~ + + Creating a new user is not strictly necessary, but it is highly + recommended. Especially for building packages, it is the safest + option to create an unprivileged user and using `doas' for doing + operations that require `root' privileges. The code block below + describes how to create a user (named `foo'), add them to the wheel + group, and to give doas permissions to the wheel group + + ,---- + | # Create the new user + | adduser foo + | + | # Add the user to the wheel group + | addgroup foo wheel + | + | # Give root permission to the wheel group using doas + | echo permit persist :wheel >> /etc/doas.conf + `---- + + You are also advised to take a look at the doas configuration file and + the manual page of doas. + + After you are finished you can switch to the new user by running + + ,---- + | su foo + `---- + + 4 Kernel ======== @@ -348,17 +380,22 @@ can be acquired as plain-text to be viewed offline with a pager from You can visit the website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) - versions are supported. + versions are supported. Note that kernel releases are quite rapid, and + the version below is likely outdated, so don't run it verbatim. ,---- | # Download the kernel and extract it - | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz - | tar xf linux-5.9.1.tar.xz + | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.19.4.tar.xz + | tar xJf linux-5.19.4.tar.xz | | # Change directory into the kernel sources - | cd linux-5.9.1 + | cd linux-5.19.4 `---- + *NOTE:* If you want to validate the kernel signature, install the + `gnupg2' package, and follow the instructions provided at + . + 4.2 Kernel dependencies ~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3