Alpine Linux - User contributions [en]

Cgit

2024-01-02T17:40:42Z

Gray wolf:

[https://git.zx2c4.com/cgit/ cgit] is a fast web-interface (CGI) for git written in the C programming language. It makes it possible for potential contributors to track and view project source code from the web instead of through a git client.

== Installation ==
{{Note|It is very recommendable that you already have a directory with an active .git working in your server. If you don't have one, install [[gitolite]] or a similar program before going further.}}
Install the package that contains cgit and git.
{{Cmd|apk add cgit git}}

Open up /etc/cgitrc with your favorite editor, in this case is vim.
{{Cmd|vim /etc/cgitrc}}

If you want to show an specific repository your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
repo.path=/var/lib/git/repositories/YOUR_GIT_REPO.git/
repo.url=CUSTOM_GIT_URL
</nowiki>}}

If you want to scan and show all the repositories you have, your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
scan-path=/var/lib/git/repositories/
</nowiki>}}

=== Run cgit using spawn-fcgi and fcgiwrap ===
Create a new service by doing a symbolic link.
{{Cmd|ln -s spawn-fcgi /etc/init.d/spawn-fcgi.cgit}}
{{Note|You should also modify the file and add -f after ${FCGI_PROGRAM} on line 99. Otherwise you will have no log and problems will be impossible to debug.}}
Create a configuration file called spawn-fcgi.cgit in /etc/conf.d/ ; the service will run fcgiwrap automatically everytime is called. It should look exactly like this:
{{Cat|/etc/conf.d/spawn-fcgi.cgit|<nowiki>FCGI_PORT=1234
FCGI_PROGRAM=/usr/bin/fcgiwrap
</nowiki>}}
{{Note|You should consider using unix domain sockets instead.}}
Start the newly created service.
{{Cmd|rc-service spawn-fcgi.cgit start}}

== Run cgit with a web service ==

=== Configure Lighttpd to work with cgit ===
Install the package that contains lighttpd if you haven't already.
{{Cmd|apk add lighttpd}}

Create a cgit.conf file into the lighttpd directory with the following content:
{{Cat|/etc/lighttpd/cgit.conf|<nowiki>server.modules += ("mod_redirect",
"mod_alias",
"mod_cgi",
"mod_fastcgi",
"mod_rewrite" )

var.webapps = "/usr/share/webapps/"
$HTTP["url"] =~ "^/cgit" {
server.document-root = webapps
server.indexfiles = ("cgit.cgi")
cgi.assign = ("cgit.cgi" => "")
mimetype.assign = ( ".css" => "text/css" )
}
url.redirect = (
"^/git/(.*)$" => "/cgit/cgit.cgi/$1",
)
</nowiki>}}

Finally, add the following line to the lighttpd.conf file:
{{Cat|/etc/lighttpd/lighttpd.conf|<nowiki>include "cgit.conf"
</nowiki>}}

Restart the lighttpd service.
{{Cmd|rc-service lighttpd restart}}

=== Configure NGINX to work with cgit pointing to a subdomain ===

Install the package that contains NGINX if you haven't already.
{{Cmd|apk add nginx}}

Create a custom configuration in the NGINX's conf.d directory.
{{Cmd|vim /etc/nginx/conf.d/git.your_domain.com.conf}}

The file should look something like this:

{{Cat|/etc/nginx/conf.d/git.your_domain.com.conf|<nowiki>server {
server_name git.your_domain.com;
root /usr/share/webapps/cgit;
try_files $uri @cgit;
location @cgit {
include fastcgi_params;
fastcgi_pass localhost:1234;
fastcgi_param SCRIPT_FILENAME $document_root/cgit.cgi;
fastcgi_param PATH_INFO $uri;
fastcgi_param QUERY_STRING $args;
}
}
</nowiki>}}
Restart the NGINX service.
{{Cmd|rc-service nginx restart}}

[[Category:Server]]
[[Category:Git]]

Cgit

2024-01-02T17:39:11Z

Gray wolf:

[https://git.zx2c4.com/cgit/ cgit] is a fast web-interface (CGI) for git written in the C programming language. It makes it possible for potential contributors to track and view project source code from the web instead of through a git client.

== Installation ==
{{Note|It is very recommendable that you already have a directory with an active .git working in your server. If you don't have one, install [[gitolite]] or a similar program before going further.}}
Install the package that contains cgit and git.
{{Cmd|apk add cgit git}}

Open up /etc/cgitrc with your favorite editor, in this case is vim.
{{Cmd|vim /etc/cgitrc}}

If you want to show an specific repository your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
repo.path=/var/lib/git/repositories/YOUR_GIT_REPO.git/
repo.url=CUSTOM_GIT_URL
</nowiki>}}

If you want to scan and show all the repositories you have, your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
scan-path=/var/lib/git/repositories/
</nowiki>}}

=== Run cgit using spawn-fcgi and fcgiwrap ===
Create a new service by doing a symbolic link.
{{Cmd|ln -s spawn-fcgi /etc/init.d/spawn-fcgi.cgit}}
{{Note|You should also modify the file and add -f after ${FCGI_PROGRAM} on line 99. Otherwise you will have no log and problems will be impossible to debug.}}
Create a configuration file called spawn-fcgi.cgit in /etc/conf.d/ ; the service will run fcgiwrap automatically everytime is called. It should look exactly like this:
{{Cat|/etc/conf.d/spawn-fcgi.cgit|<nowiki>FCGI_PORT=1234
FCGI_PROGRAM=/usr/bin/fcgiwrap
</nowiki>}}
{{Note|You should consider using unix domain sockets instead.}}
Start the newly created service.
{{Cmd|rc-service spawn-fcgi.cgit start}}

== Run cgit with a web service ==

=== Configure Lighttpd to work with cgit ===
Install the package that contains lighttpd if you haven't already.
{{Cmd|apk add lighttpd}}

Create a cgit.conf file into the lighttpd directory with the following content:
{{Cat|/etc/lighttpd/cgit.conf|<nowiki>server.modules += ("mod_redirect",
"mod_alias",
"mod_cgi",
"mod_fastcgi",
"mod_rewrite" )

var.webapps = "/usr/share/webapps/"
$HTTP["url"] =~ "^/cgit" {
server.document-root = webapps
server.indexfiles = ("cgit.cgi")
cgi.assign = ("cgit.cgi" => "")
mimetype.assign = ( ".css" => "text/css" )
}
url.redirect = (
"^/git/(.*)$" => "/cgit/cgit.cgi/$1",
)
</nowiki>}}

Finally, add the following line to the lighttpd.conf file:
{{Cat|/etc/lighttpd/lighttpd.conf|<nowiki>include "cgit.conf"
</nowiki>}}

Restart the lighttpd service.
{{Cmd|rc-service lighttpd restart}}

=== Configure NGINX to work with cgit pointing to a subdomain ===

Install the package that contains NGINX if you haven't already.
{{Cmd|apk add nginx}}

Create a custom configuration in the NGINX's conf.d directory.
{{Cmd|vim /etc/nginx/conf.d/git.your_domain.com.conf}}

The file should look something like this:

{{Cat|/etc/nginx/conf.d/git.your_domain.com.conf|<nowiki>server {
server_name git.your_domain.com;
root /usr/share/webapps/cgit;
try_files $uri @cgit;
location @cgit {
include fastcgi_params;
fastcgi_pass localhost:1234;
fastcgi_param SCRIPT_FILE $document_root/cgit.cgi;
fastcgi_param PATH_INFO $uri;
fastcgi_param QUERY_STRING $args;
}
}
</nowiki>}}
Restart the NGINX service.
{{Cmd|rc-service nginx restart}}

[[Category:Server]]
[[Category:Git]]

Cgit

2024-01-02T17:38:21Z

Gray wolf:

[https://git.zx2c4.com/cgit/ cgit] is a fast web-interface (CGI) for git written in the C programming language. It makes it possible for potential contributors to track and view project source code from the web instead of through a git client.

== Installation ==
{{Note|It is very recommendable that you already have a directory with an active .git working in your server. If you don't have one, install [[gitolite]] or a similar program before going further.}}
Install the package that contains cgit and git.
{{Cmd|apk add cgit git}}

Open up /etc/cgitrc with your favorite editor, in this case is vim.
{{Cmd|vim /etc/cgitrc}}

If you want to show an specific repository your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
repo.path=/var/lib/git/repositories/YOUR_GIT_REPO.git/
repo.url=CUSTOM_GIT_URL
</nowiki>}}

If you want to scan and show all the repositories you have, your configuration should look something like this:
{{Cat|/etc/cgitrc|<nowiki>virtual-root=/
scan-path=/var/lib/git/repositories/
</nowiki>}}

=== Run cgit using spawn-fcgi and fcgiwrap ===
Create a new service by doing a symbolic link.
{{Cmd|ln -s spawn-fcgi /etc/init.d/spawn-fcgi.cgit}}
{{Note|You should also modify the file and add -f after ${FCGI_PROGRAM} on line 99. Otherwise you will have no log and problems will be impossible to debug.}}
Create a configuration file called spawn-fcgi.cgit in /etc/conf.d/ ; the service will run fcgiwrap automatically everytime is called. It should look exactly like this:
{{Cat|/etc/conf.d/spawn-fcgi.cgit|<nowiki>FCGI_PORT=1234
FCGI_PROGRAM=/usr/bin/fcgiwrap
</nowiki>}}
Start the newly created service.
{{Cmd|rc-service spawn-fcgi.cgit start}}

== Run cgit with a web service ==

=== Configure Lighttpd to work with cgit ===
Install the package that contains lighttpd if you haven't already.
{{Cmd|apk add lighttpd}}

Create a cgit.conf file into the lighttpd directory with the following content:
{{Cat|/etc/lighttpd/cgit.conf|<nowiki>server.modules += ("mod_redirect",
"mod_alias",
"mod_cgi",
"mod_fastcgi",
"mod_rewrite" )

var.webapps = "/usr/share/webapps/"
$HTTP["url"] =~ "^/cgit" {
server.document-root = webapps
server.indexfiles = ("cgit.cgi")
cgi.assign = ("cgit.cgi" => "")
mimetype.assign = ( ".css" => "text/css" )
}
url.redirect = (
"^/git/(.*)$" => "/cgit/cgit.cgi/$1",
)
</nowiki>}}

Finally, add the following line to the lighttpd.conf file:
{{Cat|/etc/lighttpd/lighttpd.conf|<nowiki>include "cgit.conf"
</nowiki>}}

Restart the lighttpd service.
{{Cmd|rc-service lighttpd restart}}

=== Configure NGINX to work with cgit pointing to a subdomain ===

Install the package that contains NGINX if you haven't already.
{{Cmd|apk add nginx}}

Create a custom configuration in the NGINX's conf.d directory.
{{Cmd|vim /etc/nginx/conf.d/git.your_domain.com.conf}}

The file should look something like this:

{{Cat|/etc/nginx/conf.d/git.your_domain.com.conf|<nowiki>server {
server_name git.your_domain.com;
root /usr/share/webapps/cgit;
try_files $uri @cgit;
location @cgit {
include fastcgi_params;
fastcgi_pass localhost:1234;
fastcgi_param SCRIPT_FILE $document_root/cgit.cgi;
fastcgi_param PATH_INFO $uri;
fastcgi_param QUERY_STRING $args;
}
}
</nowiki>}}
Restart the NGINX service.
{{Cmd|rc-service nginx restart}}

[[Category:Server]]
[[Category:Git]]

Install Alpine in QEMU

2022-02-27T23:22:07Z

Gray wolf:

==Before You Start==

* Download the [http://alpinelinux.org/downloads latest Alpine image].
* Install QEMU on your system (e.g. <code>sudo apt install qemu</code> on Ubuntu, <code>yum -y install qemu</code> on Fedora)

If you are using alpine linux, you will like need to install:

# apk add qemu qemu-img qemu-system-x86_64 qemu-ui-gtk

==Create the Virtual Machine==

Create a disk image if you want to install Alpine Linux.

{{Cmd|qemu-img create -f qcow2 alpine.qcow2 8G}}

The following command starts QEMU with the Alpine ISO image as CDROM, the default network configuration, 512MB RAM, the disk image that was created in the previous step, and CDROM as the boot device.

{{Cmd|1=qemu-system-x86_64 -m 512 -nic user -boot d -cdrom alpine-standard-3.10.2-x86_64.iso -hda alpine.qcow2 -display gtk -enable-kvm}}

{{Tip|Remove option <code>-enable-kvm</code> if your hardware does support this.}}

Log in as <code>root</code> (no password) and run: {{Cmd|setup-alpine}}
Follow the [[Alpine_setup_scripts#setup-alpine|setup-alpine installation steps]].

Run <code>poweroff</code> to shut down the machine.

== Booting the Virtual Machine ==
After the installation, QEMU can be started from disk image (<code>-boot c</code>) without CDROM.

{{Cmd|qemu-system-x86_64 -m 512 -nic user -hda alpine.qcow2}}

[[Category:Virtualization]]

Install Alpine in QEMU

2022-02-27T22:54:19Z

Gray wolf: /* Before You Start */

==Before You Start==

* Download the [http://alpinelinux.org/downloads latest Alpine image].
* Install QEMU on your system (e.g. <code>sudo apt install qemu</code> on Ubuntu, <code>yum -y install qemu</code> on Fedora)

If you are using alpine linux, you will like need to install:

# apk add qemu qemu-img qemu-system-x86_64 qemu-ui-gtk

==Create the Virtual Machine==

Create a disk image if you want to install Alpine Linux.

{{Cmd|qemu-img create -f qcow2 alpine.qcow2 8G}}

The following command starts QEMU with the Alpine ISO image as CDROM, the default network configuration, 512MB RAM, the disk image that was created in the previous step, and CDROM as the boot device.

{{Cmd|1=qemu-system-x86_64 -m 512 -nic user -boot d -cdrom alpine-standard-3.10.2-x86_64.iso -hda alpine.qcow2}}

{{Tip|Add option <code>-enable-kvm</code> if your hardware support this.}}

Log in as <code>root</code> (no password) and run: {{Cmd|setup-alpine}}
Follow the [[Alpine_setup_scripts#setup-alpine|setup-alpine installation steps]].

Run <code>poweroff</code> to shut down the machine.

== Booting the Virtual Machine ==
After the installation, QEMU can be started from disk image (<code>-boot c</code>) without CDROM.

{{Cmd|qemu-system-x86_64 -m 512 -nic user -hda alpine.qcow2}}

[[Category:Virtualization]]

Relay email to gmail (msmtp, mailx, sendmail

2022-02-20T14:10:04Z

Gray wolf:

== Overview ==
If you're running an alpine from stick and need a way for your program to alert you through a standard gmail account

== Install msmtp ==
<pre>
sudo apk add msmtp
</pre>

== Configuration ==
Create a global configuration, "/etc/msmtprc" with content

<pre>
# Set default values for all following accounts.
defaults
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
syslog on

# Gmail
account gmail
host smtp.gmail.com
port 587
from <your email>
user <your gmail account>
password <your password>

# Set a default account
account default : gmail
aliases /etc/aliases
</pre>
{{note|Please note I've used the '''syslog on''' to send msmtp log to syslog, yet you can use the '''logfile <log_file_path>''' if you prefer to log to a file }}
{{note|Please note the aliases '''/etc/aliases''', this will help for mail/sendmail to redirect email to local user (like root) to an external email }}

== Sendmail alias ==
By default alpine comes with busybox sendmail, msmtp can act as a sendmail alternative including syntax and option, there I create a local.d script to overwrite the busybox link to msmtp.

Create a file "/etc/local.d/msmtp-sendmail.start" with below content:
<pre>
#!/bin/sh
ln -sf /usr/bin/msmtp /usr/bin/sendmail
ln -sf /usr/bin/msmtp /usr/sbin/sendmail
</pre>

Make it executable
<pre>
sudo chmod +x /etc/local.d/msmtp-sendmail.start
</pre>

and run it first time through
<pre>
sudo /etc/local.d/msmtp-sendmail.start
</pre>

== Mailx and aliases ==
Install mailx for program that uses mail (like apcupsd for monitoring UPS events)
<pre>
sudo apk add mailx
</pre>

Create an "/etc/aliases" file with content:
<pre>
root: <your external email where all email to root will be sent>

default: <default email>
</pre>

== Testing ==
Test an email, run
<pre>
echo -e "Subject: Do you love alpine?\nYes, I do!\n" | msmtp root
</pre>
{{note|'''root''' only work if you've setup /etc/aliases, otherwise put any email adress you can check instead of root}}

== Saving the configuration ==
<pre>
sudo lbu ci
</pre>

Hope it helps.

[[Category:Monitoring]]
[[Category:Mail]]

Podman

2022-02-16T15:00:04Z

Gray wolf:

== Installation ==

Podman can be installed via `podman` package in the community repository.

# apk add podman

To run podman you'll need to enable the cgroups service, consider enabling [[OpenRC#cgroups v2|cgroups v2]].

# rc-update add cgroups
# rc-service cgroups start

You might need to restart your machine for this to work properly.

If you are running on top of btrfs, consider setting storage driver to btrfs:

+ $ cat /etc/containers/storage.conf | grep 'driver ='
driver = "btrfs"

For rootless support (replace <USER> with your username):

# modprobe tun
# echo tun >>/etc/modules
# echo <USER>:100000:65536 >/etc/subuid
# echo <USER>:100000:65536 >/etc/subgid

Run an example container to verify everything works:

$ podman run --rm hello-world

Podman

2022-02-16T14:59:39Z

Gray wolf: Update for podman on 3.15

== Installation ==

Podman can be installed via `podman` package in the community repository.

# apk add podman

To run podman you'll need to enable the cgroups service, consider enabling [[OpenRC#cgroups v2|cgroups v2]].

# rc-update add cgroups
# rc-service cgroups start

You might need to restart your machine for this to work properly.

If you are running on top of btrfs, consider setting driver to btrfs:

+ $ cat /etc/containers/storage.conf | grep 'driver ='
driver = "btrfs"

For rootless support (replace <USER> with your username):

# modprobe tun
# echo tun >>/etc/modules
# echo <USER>:100000:65536 >/etc/subuid
# echo <USER>:100000:65536 >/etc/subgid

Run an example container to verify everything works:

$ podman run --rm hello-world

OpenRC

2022-02-16T14:53:14Z

Gray wolf:

== Quick-Start Information ==
Alpine Linux uses [https://wiki.gentoo.org/wiki/OpenRC OpenRC] for its init system.

The following commands are available to manage the init system:
* Basics:
{{Cmd|rc-update add <service> <runlevel>}}
{{Cmd|rc-update del <service> <runlevel>}}
{{Cmd|rc-service <service> <start stop restart> # ⇔ /etc/init.d/service <start stop restart>}}

* To check services and their set runlevels:
{{Cmd|rc-status}}

* To change to a different runlevel:
{{Cmd|rc <runlevel>}}

* Reboot/Halt/Poweroff: (And their equivalent from traditional GNU/Linux systems)
{{Cmd|reboot # ⇔ shutdown now -r}}
{{Cmd|halt # ⇔ shutdown now -H}}
{{Cmd|poweroff # ⇔ shutdown now -P}}

{{Tip|Prior to Alpine Linux 2.0.0, you might need to use the following commands instead: ''rc_add, rc_delete,'' and ''rc_status''.}}

== Available Runlevels ==
The available runlevels are:
* '''default''' - Used if no runlevel is specified. (This is generally the runlevel you want to add services to.)
* '''hotplugged'''
* '''manual'''

The special runlevels are:
* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to hold state information about the services it runs. sysinit always runs when the host first starts and should not be run again.
* '''boot''' - Generally the only services you should add to the boot runlevel are those which deal with the mounting of filesystems, set the initial state of attached peripherals and logging. Hotplugged services are added to the boot runlevel by the system. All services in the boot and sysinit runlevels are automatically included in all other runlevels except for those listed here.
* '''single''' - Stops all services except for those in the sysinit runlevel.
* '''reboot''' - Changes to the shutdown runlevel and then reboots the host.
* '''shutdown''' - Changes to the shutdown runlevel and then halts the host.

== rc-update usage ==
Usage: rc-update [options] add service <runlevel>
rc-update [options] del service <runlevel>
rc-update [options] show

Options: [suChqv]
-s, --stack Stack a runlevel instead of a service
-u, --update Force an update of the dependency tree
-h, --help Display this help output
-C, --nocolor Disable color output
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc-status usage ==
Usage: rc-status [options] [runlevel1] [runlevel2] ...

Options: [aclrsuChqv]
-a, --all Show services from all run levels
-c, --crashed Show crashed services
-l, --list Show list of run levels
-r, --runlevel Show the name of the current runlevel
-s, --servicelist Show service list
-u, --unused Show services not assigned to any runlevel
-h, --help Display this help output
-C, --nocolor Disable color output
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc-service usage ==
Usage: rc-service [options]

Options: [e:ilr:ChqVv]
-e, --exists <arg> tests if the service exists or not
-i, --ifexists if the service exists then run the command
-l, --list list all available services
-r, --resolve <arg> resolve the service name to an init script
-h, --help Display this help output
-C, --nocolor Disable color output
-V, --version Display software version
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc usage ==
Usage: rc [options]

Options: [a:o:s:SChqVv]
-a, --applet <arg> runs the applet specified by the next argument
-o, --override <arg> override the next runlevel to change into
when leaving single user or boot runlevels
-s, --service <arg> runs the service specified with the rest
of the arguments
-S, --sys output the RC system type, if any
-h, --help Display this help output
-C, --nocolor Disable color output
-V, --version Display software version
-v, --verbose Run verbosely
-q, --quiet Run quietly

== cgroups v2 ==

You can enable cgroups v2 by editing /etc/rc.conf and setting rc_cgroup_mode to unified.

[[Category:Booting]]

OpenRC

2022-02-16T14:53:00Z

Gray wolf:

== Quick-Start Information ==
Alpine Linux uses [https://wiki.gentoo.org/wiki/OpenRC OpenRC] for its init system.

The following commands are available to manage the init system:
* Basics:
{{Cmd|rc-update add <service> <runlevel>}}
{{Cmd|rc-update del <service> <runlevel>}}
{{Cmd|rc-service <service> <start stop restart> # ⇔ /etc/init.d/service <start stop restart>}}

* To check services and their set runlevels:
{{Cmd|rc-status}}

* To change to a different runlevel:
{{Cmd|rc <runlevel>}}

* Reboot/Halt/Poweroff: (And their equivalent from traditional GNU/Linux systems)
{{Cmd|reboot # ⇔ shutdown now -r}}
{{Cmd|halt # ⇔ shutdown now -H}}
{{Cmd|poweroff # ⇔ shutdown now -P}}

{{Tip|Prior to Alpine Linux 2.0.0, you might need to use the following commands instead: ''rc_add, rc_delete,'' and ''rc_status''.}}

== Available Runlevels ==
The available runlevels are:
* '''default''' - Used if no runlevel is specified. (This is generally the runlevel you want to add services to.)
* '''hotplugged'''
* '''manual'''

The special runlevels are:
* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to hold state information about the services it runs. sysinit always runs when the host first starts and should not be run again.
* '''boot''' - Generally the only services you should add to the boot runlevel are those which deal with the mounting of filesystems, set the initial state of attached peripherals and logging. Hotplugged services are added to the boot runlevel by the system. All services in the boot and sysinit runlevels are automatically included in all other runlevels except for those listed here.
* '''single''' - Stops all services except for those in the sysinit runlevel.
* '''reboot''' - Changes to the shutdown runlevel and then reboots the host.
* '''shutdown''' - Changes to the shutdown runlevel and then halts the host.

== rc-update usage ==
Usage: rc-update [options] add service <runlevel>
rc-update [options] del service <runlevel>
rc-update [options] show

Options: [suChqv]
-s, --stack Stack a runlevel instead of a service
-u, --update Force an update of the dependency tree
-h, --help Display this help output
-C, --nocolor Disable color output
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc-status usage ==
Usage: rc-status [options] [runlevel1] [runlevel2] ...

Options: [aclrsuChqv]
-a, --all Show services from all run levels
-c, --crashed Show crashed services
-l, --list Show list of run levels
-r, --runlevel Show the name of the current runlevel
-s, --servicelist Show service list
-u, --unused Show services not assigned to any runlevel
-h, --help Display this help output
-C, --nocolor Disable color output
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc-service usage ==
Usage: rc-service [options]

Options: [e:ilr:ChqVv]
-e, --exists <arg> tests if the service exists or not
-i, --ifexists if the service exists then run the command
-l, --list list all available services
-r, --resolve <arg> resolve the service name to an init script
-h, --help Display this help output
-C, --nocolor Disable color output
-V, --version Display software version
-v, --verbose Run verbosely
-q, --quiet Run quietly

== rc usage ==
Usage: rc [options]

Options: [a:o:s:SChqVv]
-a, --applet <arg> runs the applet specified by the next argument
-o, --override <arg> override the next runlevel to change into
when leaving single user or boot runlevels
-s, --service <arg> runs the service specified with the rest
of the arguments
-S, --sys output the RC system type, if any
-h, --help Display this help output
-C, --nocolor Disable color output
-V, --version Display software version
-v, --verbose Run verbosely
-q, --quiet Run quietly

== cgroups v2 ==

By can enable cgroups v2 by editing /etc/rc.conf and setting rc_cgroup_mode to unified.

[[Category:Booting]]

LXC

2021-08-08T00:25:29Z

Gray wolf: Update for lxc-download, alpine template is not package by default (anymore?)

[https://linuxcontainers.org/ Linux Containers (LXC)] provides containers similar to BSD Jails, Linux VServers and Solaris Zones. It gives the impression of virtualization, but shares the kernel and resources with the "host". You can use lxc directly or through [[LXD]].

== Installation ==
Install the required packages:
{{Cmd|apk add lxc bridge lxcfs lxc-download xz}}

If you want to create containers other than Alpine, you'll need lxc-templates:

{{Cmd|apk add lxc-templates}}

== Upgrading from 2.x ==

Starting with Alpine 3.9, we ship LXC version 3.1.
LXC 3.x has major changes which can and will break your current setup.
LXC 3.x will NOT ship with legacy container templates. Check your current container configs to see if you have any includes pointing to files that don't exist (shipped by legacy templates).
For example if you use Alpine containers created with the Alpine template, you'll need to install:

apk add lxc-templates-legacy-alpine

Also make sure you convert your LXC config files to the new 2.x format (this is now required).

lxc-update-config -c /var/lib/lxc/container-name/config

Make sure you have removed '''cgroup_enable''' from your cmdline as this will fail to mount cgroups and fail LXC service.

== Prepare network on host ==
Set up a [[bridge]] on the host. Example ''/etc/network/interfaces'':
<pre>
auto br0
iface br0 inet dhcp
bridge-ports eth0
</pre>

Create a network configuration template for the guests, ''/etc/lxc/default.conf'':
<pre>
lxc.net.0.type = veth
lxc.net.0.link = br0
lxc.net.0.flags = up
lxc.net.0.hwaddr = fe:xx:xx:xx:xx:xx
</pre>

== Grsecurity restrictions ==

'''NOTE''': As of Alpine version 3.8, we no longer ship grsecurity and it should not be used in lxc setup.

Some restrictions will be applied when using a grsecurity kernel (Alpine Linux default kernel).
The most notable is the use of lxc-attach which will not be allowed because of GRKERNSEC_CHROOT_CAPS.
To solve this, we will have to disable the grsec restriction by creating a sysctl profile for lxc.
Create the following file ''/etc/sysctl.d/10-lxc.conf'' and add:
<pre>
kernel.grsecurity.chroot_caps = 0
</pre>

There are a few other restrictions that can prevent proper container operation.
When things do not work as expected, check the kernel log with dmesg to see if grsec prevented things from happening.

Other possible restrictions are:

<pre>
kernel.grsecurity.chroot_deny_chroot = 0
kernel.grsecurity.chroot_deny_mount = 0
kernel.grsecurity.chroot_deny_mknod = 0
kernel.grsecurity.chroot_deny_chmod = 0
</pre>

When you finish creating your new sysctl profile, you can apply it by restarting sysctl service:

<pre>
rc-service sysctl restart
</pre>

NOTE: Always consult the [https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options Grsecurity documentation] before applying these settings.

== Create a guest ==

=== Picking from the list ===

{{Cmd|lxc-create -n guest1 -f /etc/lxc/default.conf -t download}}

And just pick from the list. lxc-download and xz can be uninstalled after you are done.

=== Alpine Template ===

{{Cmd|lxc-create -n guest1 -f /etc/lxc/default.conf -t alpine}}

This will create a ''/var/lib/lxc/guest1'' directory with a ''config'' file and a ''rootfs'' directory.

Note: by default, the alpine template '''does not have networking service on''', you will need to add it using lxc-console

If running on x64 compatible hardware, it is possible to create a 32bit guest:

{{Cmd|lxc-create -n guest1 -f /etc/lxc/default.conf -t alpine -- --arch x86}}

=== Debian template ===

In order to create a debian template container you'll need to install some packages:

{{Cmd|apk add debootstrap rsync}}

You'll need to turn off some grsecurity chroot options otherwise the debootstrap will fail:

{{Cmd|echo 0 > /proc/sys/kernel/grsecurity/chroot_caps
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chroot
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mount
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mknod
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chmod
}}

Remember to turn them back on, or simply reboot.

Now you can run:
{{Cmd|SUITE{{=}}wheezy lxc-create -n guest1 -f /etc/lxc/default.conf -t debian}}

=== Ubuntu template ===

In order to create an ubuntu template container, you'll need to turn off some grsecurity chroot options:

{{Cmd|echo 0 > /proc/sys/kernel/grsecurity/chroot_caps
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chroot
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mount
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mknod
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chmod
}}

Remember to turn them back on, or simply reboot.

Now you can run (replace %MIRROR% with the actual hostname, for example: http://us.archive.ubuntu.com/ubuntu/)

{{Cmd|lxc-create -n guest2 -f /etc/lxc/default.conf -t ubuntu -- -r xenial -a amd64 -u user --password secretpassword --mirror $MIRROR }}

{{Warning|Be sure to set systemd_container to yes in /etc/conf.d/lxc.CONTAINER. Otherwise, most functionality will be broken}}

=== Unprivileged LXC images (Alpine / Debian / Ubuntu / Centos etc..) ===

To enable unprivileged containers, one must create a uidgid map:

echo root:1000000:65536 | tee -a /etc/subuid
echo root:1000000:65536 | tee -a /etc/subgid

This creates a uid and gid map for the root user starting at 1000000 with a size of 65536.

To configure containers to use this mapping, add the following lines to the configuration:

lxc.idmap = u 0 1000000 65536
lxc.idmap = g 0 1000000 65536

This can be in the global or container-specific configuration.

To create an unprivileged lxc container, you need to use the download template. The download template must be installed:

{{Cmd|apk add gnupg xz lxc-download
lxc-create -n container-name -t download}}
choose the Distribution | Release | Architecture.

To be able to log in to a Debian container, you currently need to:
{{Cmd|rm /lib/systemd/system/container-getty\@.service}}

You can also [http://without-systemd.org/wiki/index.php/How_to_remove_systemd_from_a_Debian_jessie/sid_installationers remove Systemd from the container].

== Starting/Stopping the guest ==

First, you should enable the cgroup script:

{{Cmd|rc-update add cgroups}}

If you don't want to reboot, you can start the service by running

{{Cmd|rc-service cgroups start}}

Create a symlink to the ''/etc/init.d/lxc'' script for your guest.
{{Cmd|ln -s lxc /etc/init.d/lxc.guest1}}

You can start your guest with:
{{Cmd|/etc/init.d/lxc.guest1 start}}

Stop it with:
{{Cmd|/etc/init.d/lxc.guest1 stop}}

Make it autostart at boot-up with:
{{Cmd| rc-update add lxc.guest1}}

You can add to the container config: <code>lxc.start.auto = 1</code>

{{Cmd|rc-update add lxc}}

to autostart containers with the lxc service only.

== Connecting to the guest ==
By default, sshd is not installed. You'll have to attach to the container or connect to the virtual console. This is done with:

{{Cmd|lxc-attach -n guest1}}

Type exit to detach from the container again (please check the grsec notes above)

== Connect to virtual console ==

{{Cmd|lxc-console -n guest1}}

To disconnect, press {{key|Ctrl}}+{{key|a}} {{key|q}}

== Deleting a guest ==
Make sure the guest is stopped, then run:
{{Cmd|lxc-destroy -n guest1}}
This will erase everything, without asking any questions. It is equivalent to: {{Cmd|rm -r /var/lib/lxc/guest1}}

== Advanced ==

=== Creating a LXC container without modifying your network interfaces ===

The problem with bridging is that the interface you bridge gets replaced with your new bridge interface.
Let's say you have interface eth0 that you want to bridge. Your eth0 interface gets replaced with the br0 interface that you create. It also means that the interface you use needs to be placed into promiscuous mode to catch all the traffic that could de destined to the other side of the bridge, which may not be what you want.

The solution is to create a dummy network interface, bridge that, and set up NAT so that traffic out of your bridge interface gets pushed through the interface of your choice.

Let's create that dummy interface (thanks to ncopa for talking me out of macvlan and pointing out the dummy interface kernel module)

{{Cmd|modprobe dummy}}

This will create a dummy interface called dummy0 on your host. To create this interface on every boot, append "dummy" to /etc/modules:

Now we will create a bridge called br0

{{Cmd |brctl addbr br0
brctl setfd br0 0 }}

and then make that dummy interface one end of the bridge

{{Cmd | brctl addif br0 dummy0 }}

Next, let's give that bridged interface a reason to exist:

{{ Cmd | ifconfig br0 192.168.1.1 netmask 255.255.255.0 up}}

Create a file for your container. Let's say /etc/lxc/bridgenat.conf, with the following settings.

<pre>
lxc.net.0.type = veth
lxc.net.0.flags = up
lxc.net.0.link = br0
lxc.net.0.name = eth1
lxc.net.0.ipv4.address = 192.168.1.2/24 192.168.1.255
lxc.net.0.ipv4.gateway = 192.168.1.1
lxc.net.0.veth.pair = veth-if-0
</pre>

and build your container with that file:

{{ Cmd | lxc-create -n alpine -f /etc/lxc/bridgenat.conf -t alpine }}

You should now be able to ping your container from your host, and your host from your container.

Your container needs to know where to push traffic that isn't within it's subnet. To do so, we tell the container to route through the bridge interface, br0
From inside the container run

{{ Cmd | route add default gw 192.168.1.1 }}

The next step is to push the traffic coming from your private subnet over br0 out through your internet facing interface, or any interface you chose

We are messing with your IP tables here, so make sure these settings don't conflict with anything you may have already set up.

Say eth0 was your internet facing network interface, and br0 is the name of the bridge you made earlier. We'd do this:

{{ Cmd | echo 1 > /proc/sys/net/ipv4/ip_forward
iptables --table nat --append POSTROUTING --out-interface eth0 -j MASQUERADE
iptables --append FORWARD --in-interface br0 -j ACCEPT
}}

Now you should be able to route through your bridge interface to the internet facing interface of your host from your container, just like at home!

You could also have a dhcp server running on your host, and set it up to give IP addresses from your private subnet to any container that requests it, and then have one template for multiple alpine LXC containers, perfect for alpine development :)

=== Using static IP ===

If you're using static IP, you need to configure this properly on the guest /etc/network/interfaces. To stay in line with the above example, modify ''/var/lib/lxc/guest1/rootfs/etc/network/interfaces''

from

#auto lo
iface lo inet loopback
auto eth0
iface eth0 inet '''dhcp'''

to

#auto lo
iface lo inet loopback
auto eth0
iface eth0 inet '''static'''
address <lxc-container-ip> # IP which the lxc container should use
gateway <gateway-ip> # IP of gateway to use, mostly same as on lxc-host
netmask <netmask>

=== mem and swap ===

{{Cmd|vim /boot/extlinux.conf}}

{{Cmd|
APPEND initrd{{=}}initramfs-3.10.13-1-grsec root{{=}}UUID{{=}}7cd8789f-5659-40f8-9548-ae8f89c918ab modules{{=}}sd-mod,usb-storage,ext4 quiet cgroup_enable{{=}}memory swapaccount{{=}}1
}}

=== checkconfig ===
{{Cmd|lxc-checkconfig}}

{{Cmd|
Kernel configuration not found at /proc/config.gz; searching...
Kernel configuration found at /boot/config-3.10.13-1-grsec
--- Namespaces ---
Namespaces: enabled
Utsname namespace: enabled
Ipc namespace: enabled
Pid namespace: enabled
User namespace: missing
Network namespace: enabled
Multiple /dev/pts instances: enabled

--- Control groups ---
Cgroup: enabled
Cgroup clone_children flag: enabled
Cgroup device: enabled
Cgroup sched: enabled
Cgroup cpu account: enabled
Cgroup memory controller: missing
Cgroup cpuset: enabled

--- Misc ---
Veth pair device: enabled
Macvlan: enabled
Vlan: enabled
File capabilities: enabled

Note : Before booting a new kernel, you can check its configuration
usage : CONFIG{{=}}/path/to/config /usr/bin/lxc-checkconfig

}}

=== VirtualBox ===

In order for the network to work on containers, you need to set "Promiscuous Mode" to "Allow All" in VirtualBox settings for the network adapter.

[[File:VirtualBoxNetworkAdapter.jpg]]

[[Category:Virtualization]]

=== postgreSQL ===

Inside the container run: {{Cmd|chmod go+w /dev/null}} to fix {{Cmd|rc-service postgresql start}}

=== openVPN ===

see [[Setting_up_a_OpenVPN_server#openVPN_and_LXC]]

== LXC 1.0 Additional information ==

Some info regarding new features in LXC 1.0

https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/

== See also ==
* [[Howto-lxc-simple]]

Installation

2020-10-14T16:10:47Z

Gray wolf: Rewrite to simplify and improve the document

While Alpine Linux is often used as base image for linux containers, it can of course be also installed on bare metal machine as well. That is the focus of this document.

__TOC__
__FORCETOC__

= Quick Requirements =

Nearly any hardware should run Alpine Linux but the following basic requirements are recommended:

* At least 128MB of RAM for server without GUI, or at least 1.6GB for graphical desktop
* At least 1GB storage device for server without GUI, or at least 10GB for graphical desktop with web browsing

For more information, see [[Requirements]].

[[File:Installation-alpine-alpine-setup-2-boot.png|350px|thumb|right|Installation : setup-alpine : booting process until login prompt]]

= Installation Overview =

The following steps are brief and intended for the common case; for complete info and other architectures, please consult the [[Alpine newbie install manual]].

== 1. Download the installation image ==

You need to acquire installation image, usually from [http://alpinelinux.org/downloads]. Most likely you will want the standard edition. Make sure you download the image for correct architecture.

== 2. Create the installation medium ==

Either you can burn the image onto CD/DVD, you use usb stick for the installation.

Under linux, you can use the dd for that:

<code><nowiki>dd if=<source iso> of=<target device> bs=4M; sync</nowiki></code>

Make sure that the device '''does not''' include partition number, so example from my machine:

<code><nowiki>dd if=~/Downloads/alpine-standard-3.10.2-x86_64.iso of=/dev/sdb bs=4M</nowiki></code>

The target device '''will be erased''', so make sure you use something without any data you do not
want to lose.

== 3. Boot and install process ==

Log in as the user <code>root</code> and execute [[Alpine_setup_scripts#setup-alpine|setup-alpine]] and answer all the questions asked. Quick step-by-step walkthrough (go read [[Alpine_setup_scripts#setup-alpine|setup-alpine]] for more in-depth explanation):

[[File:Installation-alpine-alpine-setup-3-setup-scripts.png|350px|thumb|right|Installation : setup-alpine : complete process single install]]

===== Keyboard layout and variant =====

As you would expect, this is keyboard layout you want. If you are not sure, answering <code>us</code> to both layout and variant will get you started and you can change it later.

===== System hostname =====

Pick the name of your computer, while not mandatory, something unique if prefered. Or you can just use <code>localhost</code> if you do not care.

===== Network configuratinon =====

You will be asked ''which'' network interface you want to configure, if you are not sure, picking the offered default would likely work. Once selected, you will be asked <code>Ip address for XXX?</code>, you can either assign an IP address or write <code>dhcp</code>, which will mean take configuration from the network (the <code>dhcp</code> works great for home networks where you do not care about IP of your machine).

Assuming you decided to configure network yourself with IP address, you will also be asked for netmask, gateway, dns domain name and dns server IP. Correct values for there are beyond the scope of this document, please refer to your network administrator for guidance instead.

===== Password for root =====

Well this one is obvious.

===== Timezone =====

For servers, it is common to use UTC, for non-server machines, your local timezone should be likely used. Notice that you can use <code>?</code> to list the timezone.

===== HTTP/FTP Proxy =====

Most likely default (<code>none</code>) is the correct choice.

===== NTP client =====

Which client to use for keeping the system clock in sync, default works for most people.

===== Mirror =====

Pick mirror from which to download updates, <code>1</code> is CDN backed by Fastly, so reasonable choice for most people.

===== SSH server =====

Which SSH server do you want to configure on your machine. If you know that you will '''not''' connect to your machine remotely (most laptops for example), <code>none</code> should be used. Otherwise, the default (<code>openssh</code>) is a good pick.

===== Disk setup =====

Here your can pick the device to install the system on and also the mode in which it should be installed. For overview of the modes, see [[Alpine_setup_scripts#setup-modes|this]]. If you are not sure or just starting up, <code>sys</code> is likely what you want, it is the same mode that other distributions use for installation.

'''All data on the chosen device will be erased!'''

===== Reboot =====

After the script finishes installing the system, it will tell you to reboot. Note that:

* If the configured [[Alpine_setup_scripts#sys_mode|runtime mode was "sys"]], then remove the initial installation media to boot the newly installed system.
* If the configured [[Alpine_setup_scripts#diskless_mode|runtime mode was "data"]], then keep the installation media inserted to boot the newly installed system.

Then execute <code>reboot</code> and once the machine restarts and finishes booting up, you should see login prompt of your new Alpine Linux installation.

The installation script only installs the base operating system. Applications such as a web server, mail server, desktop environment, or web browser are not installed and <code>root</code> is the only normal user. For instructions on proceeding after installation, please see [[Tutorials_and_Howtos#Post-Install|Tutorials_and_Howtos Post-Install section]].

= Further Documentation =

More specific instructions and instructions for other architectures or machines (e.g. ARM, RPi, etc) are defined in [[Tutorials_and_Howtos#Installation:_Use_cases|Installation:_Use_cases]]. Also see the following wiki pages for more information:

* [[FAQ|FAQs]]
* [[Tutorials and Howtos]]
* [[Contribute|How to Contribute]]
* [[Developer Documentation]]
* [[Newbie Alpine Ecosystem]]

== External links ==

* [https://mckayemu.github.io/alpineinstalls/ More information, in Spanish]

[[Category:Installation]]

Installation

2020-10-14T15:25:46Z

Gray wolf: Fix link label and move into separate subsection

Alpine Linux can be installed as the main operating system on a physical machine ("bare metal"), including on embedded devices. For example, [https://en.wikipedia.org/wiki/PostmarketOS PostmarketOS] is a smartphone operating system based on Alpine. Another old examle are [https://www.adelielinux.org/ Adélie Linux] is a complete end-user distribution started as geento fork but using Alpine Linux software. While this use case is less common than Alpine Linux's main use as a base system for container images in systems (like Docker), this document describes how Alpine can be installed as the primary operating system for a computer.

Alpine in fact works as a [https://en.wikipedia.org/wiki/Live_USB live system]—any install disk of Alpine can also be run without installing to local storage of the machine it's booted on, running directly from the install media!

__TOC__
__FORCETOC__

= Quick Requirements =

Nearly any hardware should run Alpine Linux but the following basic requirements are recommended:

* At least 128MB of RAM for server without GUI, or at least 1.6GB for graphical desktop
* At least 1GB storage device for server without GUI, or at least 10GB for graphical desktop with web browsing

For more information, see [[Requirements]].

[[File:Installation-alpine-alpine-setup-2-boot.png|350px|thumb|right|Installation : setup-alpine : booting process until login prompt]]

= Installation Overview =

The following steps are brief and intended for the common case; for complete info and other architectures, please consult the [[Alpine newbie install manual]].

== 1. Download the media source ==

The most common is to grab an ISO from [http://alpinelinux.org/downloads]. Take note of architectures in green buttons.

== 2. Dump, burn or flash the image ==

Dump the ISO image onto a media source like USB/SD flashing; or CD/DVD/BR disk with burning software.
In Linux, you can use <code><nowiki>dd if=<your iso filename> of=<your target media> bs=1M; sync</nowiki></code>, to flash a USB drive or SD card as target media install.

== 3. Boot and install process ==

Log in as the user <code>root</code> by typing <code>root</code> and hitting ''enter''. Then execute <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code>, answering the questions and hitting ''enter'' after each:

[[File:Installation-alpine-alpine-setup-3-setup-scripts.png|350px|thumb|right|Installation : setup-alpine : complete process single install]]

* '''Select keyboard layout''': Choose your keyboard layout, e.g. ''us'' or ''es''.
** '''Select variant''': Choose your keyboard layout variant, e.g. ''us-nodeadkeys'' or ''es-winkeys''.
* '''Enter system hostname''': Choose the name of your computer; '''localhost''' is good enough and recommended for starting.
* '''Initialize network cards''': Here most people can just go with the default (just press enter).
** '''Any manual configuration''': Perform other configuration if needed, otherwise just type "no" and hit enter.
** '''Select domain name''': This is not commonly asked, you can just hit enter.
* '''DNS nameservers?''': If asked, <code>8.8.8.8</code> is a recommended default that will be good for most people.
* '''Changing password for root''': Next a root password must be defined. Input a passphrase; what you type won't be shown on the screen.
** '''Retype password''': Type the same passphrase to confirm the root password; what you type won't be shown on the screen.
* '''Which timezone to choose?''': Set it to your local time zone or hit enter for <code>UTC</code>.
* '''Proxy chooser''': Type <code>none</code> and hit enter if you're not using a proxy.
* '''Which NTP client to run?''': This is for keeping the system clock in sync. The default is good enough for most people.
* '''Enter mirror number''': <code>1</code> is a good choice for most people.
* '''Which SSH server?''': An SSH server allows you to remotely manage your machine. The default is good enough for most people.
* '''Disk Setup''' Choose how to set up your disks.
** '''Which disks would you like to use?''': Choose the disk where files will be installed. Usually <code>sda</code> is the hard disk and <code>sdb</code> is the USB boot or CD/DVD image.
** '''How would you like to use it?''': Type "sys" and then press enter. This will cause the OS to be installed to the chosen disk—similar to how other distributions work.

Take care that '''all data on your chosen disk will be erased'''. A final question will prompt you to continue. After confirming by typing 'y' and hitting enter, you cannot turn back.

After the script finishes installing the system, it will tell you to reboot. Note that:

* If the configured [[Alpine_setup_scripts#sys_mode|runtime mode was "sys"]], then remove the initial installation media to boot the newly installed system.
* If the configured [[Alpine_setup_scripts#diskless_mode|runtime mode was "data"]], then keep the installation media inserted to boot the newly installed system.

To reboot, type <code>reboot</code> and hit enter. If you just wish to turn off the machine after installing, type <code>poweroff</code> instead.

= Further Documentation =

The installation script only installs the base operating system. Applications such as a web server, mail server, desktop environment, or web browser are not installed and <code>root</code> is the only normal user. For instructions on proceeding after installation, please see [[Tutorials_and_Howtos#Post-Install|Tutorials_and_Howtos Post-Install section]].

More specific instructions and instructions for other architectures or machines (e.g. ARM, RPi, etc) are defined in [[Tutorials_and_Howtos#Installation:_Use_cases|Installation:_Use_cases]]. Also see the following wiki pages for more information:

* [[FAQ|FAQs]]
* [[Tutorials and Howtos]]
* [[Contribute|How to Contribute]]
* [[Developer Documentation]]
* [[Newbie Alpine Ecosystem]]

== External links ==

* [https://mckayemu.github.io/alpineinstalls/ More information, in Spanish]

[[Category:Installation]]

Radeon Video

2019-12-22T00:14:51Z

Gray wolf:

{{TOC right}}

The following instructions are for modern AMD GPU chipsets covered by the radeon driver.

== Setup Xorg/udev ==

# Run the <code>[[Alpine setup scripts#setup-xorg-base|setup-xorg-base]]</code> script.
# Install the Xorg AMD video drivers: {{Cmd|# apk add xf86-video-ati}}
# For newer devices, use: {{Cmd|# apk add xf86-video-amdgpu}}
# Enable [[#Kernel Modesetting (KMS)]]. Specifically, the <code>fbcon</code> module is necessary, or leaving Xorg (via <code>Ctrl+Alt+F1</code> or quitting) will result in a black screen until the machine is power cycled. If you have already launch Xorg and don't want to experience this effect, you can <code>modprobe fbcon</code> while Xorg is running.

== Kernel Modesetting (KMS) ==

To enable [[KMS]] at boot:
# Add the <code>radeon</code> or <code>amdgpu</code> and <code>fbcon</code> modules to {{Path|/etc/modules}}: {{Cmd|$ echo radeon >> /etc/modules<br />$ echo fbcon >> /etc/modules}} or {{Cmd|$ echo amdgpu >> /etc/modules<br />$ echo fbcon >> /etc/modules}}
# Install <code>mkinitfs</code>: {{Cmd|apk add mkinitfs}}
# Enable the <code>kms</code> feature in the <code>mkinitfs</code> configuration by adding it to the <var>features</var> variable, e.g., {{cat|/etc/mkinitfs/mkinitfs.conf|features{{=}}"keymap cryptsetup kms ata base ide scsi usb virtio ext4"}}
# Run <code>mkinitfs</code>.
# Reboot to test the configuration.

== Troubleshooting ==
=== Fixing MESA-LOADER errors===
{{Obsolete|Alpine no longer ships with the ''linux-hardened'' kernel}}

The ''linux-hardened'' kernel package places restrictions on sysfs and will prevent the MESA-LOADER from working as a normal user even if added to the video group.

See https://bugs.alpinelinux.org/issues/7265

Either switch to the ''linux-vanilla'' package or apply the '''grsec_sysfs_restrict=0''' kernel parameter to allow normal users to access hardware acceleration on the desktop.

=== Fixing a frozen X11 when invoking startx ===

You may need to set the AccelMethod to exa not glamor which is the default for the driver.

{{cat|/etc/X11/xorg.conf|
Section "Device"
Option "AccelMethod" "exa"
Identifier "Card0"
Driver "radeon"
BusID "PCI:1:0:0"
EndSection}}

= =
* [https://wiki.archlinux.org/index.php/ATI archlinux.org / ATI]
* [https://wiki.archlinux.org/index.php/Xorg archlinux.org / Xorg]

[[Category:Drivers]]

Kernel Modesetting

2019-12-22T00:13:29Z

Gray wolf:

{{Expand|Needs nVidia driver information}}

; Intel
: See [[Intel_Video#Kernel_Modesetting_(KMS)]]
; Radeon
: See [[Radeon_Video#Kernel_Modesetting_(KMS)]]
; Nouveau
: See [[Nouveau_Video#Kernel_Modesetting_(KMS)]]
; nVidia
: {{Todo|Find out how KMS works with nVidia drivers}}

= =
* [https://wiki.archlinux.org/index.php/Kernel_mode_setting Kernel mode setting] archlinux.org

[[Category:Kernel]]

Kernel Modesetting

2019-12-22T00:10:57Z

Gray wolf: Add links to amdgpu and nouveau wiki pages (will be done later)

{{Expand|Needs nVidia driver information}}

; Intel
: See [[Intel_Video#Kernel_Modesetting_(KMS)]]
; Amdgpu
: See [[Amdgpu_Video#Kernel_Modesetting_(KMS)]]
; Radeon
: See [[Radeon_Video#Kernel_Modesetting_(KMS)]]
; Nouveau
: See [[Nouveau_Video#Kernel_Modesetting_(KMS)]]
; nVidia
: {{Todo|Find out how KMS works with nVidia drivers}}

= =
* [https://wiki.archlinux.org/index.php/Kernel_mode_setting Kernel mode setting] archlinux.org

[[Category:Kernel]]

Zero-To-Awall

2019-02-25T13:31:23Z

Gray wolf:

= Awall for dummies =

This howto is aimed at users with no (or little) experience with iptables and other firewall frameworks (like Shorewall).

This howto is going to be split into 5 parts.

# Defining our base json file which holds our zones and base policies.
# Creating service policies.
# Using aliases and custom services.
# Enabling and testing policies.
# Finishing up and making it start (at boot)

NOTE: please be aware that all configuration files are stored as JSON files. JSON is not a human friendly standard,
for instance it does not support comments so you will have to move them outside of the json structure.
Beginners should use a decent text editor with JSON highlight support which will make your life easier.
Since recent versions of [[Alpine Wall|awall]] it is also possible to use yaml instead of json but this is out of the scope of this howto.

== Base policies ==

Creating zones depends on the function of your firewall. Is it installed on a endpoint (server) or will it act as a router and filter/forward.
For this howto we assume you are going to setup a router and use NAT to forward services (ports) to different hosts on your network.

For each interface on router we will setup a zone and assign it a zone name. We do this by creating the following file: /etc/awall/private/base.json
<pre>
{
"description": "Base zones and policies",

"zone": {
"WAN": { "iface": "eth0" },
"LAN": { "iface": "eth1" },
"VPN": { "iface": "tun+" }
},

"policy": [
{ "in": "VPN", "action": "accept" },
{ "out": "VPN", "action": "accept" },
{ "in": "LAN", "action": "accept" },
{ "out": "LAN", "action": "accept" },
{ "in": "_fw", "action": "accept" },
{ "in": "_fw", "out": "WAN" , "action": "accept" },
{ "in": "WAN", "action": "drop" }
],

"snat": [ { "out": "WAN" } ],

"clamp-mss": [ { "out": "WAN" } ]

}
</pre>

Lets break this down into sections

=== description ===

The description is here just for reference and will be used by <code>awall list</code>.

=== zone ===

This is where our zones are defined. Zones are defined based on a interface and assigned a name to be used in your policies.
In our example you can see that we have two real interfaces eth0 and eth1 and one or more virtual interfaces tun+ (the plus sign stands for any digit like tun0 tun1 and so on). In case you are installing awall on an endpoint (a server) then you will most probably not have the eth1 interfaces and can leave it out. In our example the tun+ interface is added as it is very commonly used like when using openvpn.

=== policy ===

These are our main policies. It will tell our firewall what to do with when a packet enters or leaves from one of the zones (interfaces).
You will notice a special <code>_fw</code> name which means the internal firewall (the local machine) which means the packet does not leave the firewall via another interface but should be send to one of the local services.
You can see that we by default do not filter any package coming from or going to our VPN zone/interface. You could instead change the default action to drop all packets and create separate policies to allow specific traffic but this is out of the scope of this howto.

=== snat ===

Apply source nat for outgoing packets. This is only needed if your firewall acts as a router and traffic behind the router needs a modified source address (translate from local ip to public ip).

=== clamp-mss ===

https://github.com/alpinelinux/awall#mss-clamping-rules

== Service policies ==

Now that we have the base firewall in place we can start to define specific policies so our services will be reachable from the outside world.\
By default we are blocking all traffic coming in on our WAN interface (action=drop). The first thing we want to open is our SSH port/service. To do this we need to create a new policy inside the "optional" directory.
You could be wondering why the optional name, thats is because mandatory policies are stored in <code>/usr/share/awall/mandatory</code> and not to be touched and our optional policies can be enabled/disabled on the run.

=== SSH service ===

To add our SSH policies we create a new file: /etc/awall/optional/ssh.json
<pre>
{
"description": "Allow rate-limited SSH on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ssh",
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
]
}
</pre>

==== description ====

This is similar for any policy

==== Filter ====

This is the actual filter that is currently set to drop the packets arriving or leaving the interface.

===== in =====

The interface the packets arrive on, in this case its the WAN interface.

===== out =====

The interface the packets leave on, in this case its _fw which means it does not leave our firewall/device and is targeted at our local SSH service.

===== service =====

This is the service definition provided by awall or a custom service which we will discuss later on.

===== action =====

The action on the packet, this inverts the default action of drop and accepts the packets.

===== conn-limit =====

This is a special feature of our firewall/iptables to allow only a certain amount of packets in a certain amount of time. For more information please check our awall manual.

=== SSH to another Host ===

edit the following file: /etc/awall/optional/ssh-to-hostname.json

<pre>
{

"description": "Forward SSH to hostname",

"filter": [
{
"in": "WAN",
"service": { "proto": "tcp", "port": 22001 },
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
],

"dnat": [
{
"in": "WAN",
"dest": "$SERVER",
"service": { "proto": "tcp", "port": 22001 },
"to-port": "22"
}
]
}
</pre>

Lets discuss the differences between this policy and the previous SSH policy.

==== Filter ====

===== service =====

Because port 22 is already in use by our own firewall, we need to listen on a different port. In this example we listen on port 22001.
And because we are not using the default port 22 we need to define our own service specification.

==== dnat ====

Also known as destination NAT.

===== dest =====

The destination the packet will be forwarded to. In this case we are using a variable named $HOSTNAME. Anywhere in your policies you can define your own variables and use them.
In our case we have used a file in /etc/awall/private/aliases.json more on this topic later on.

===== to-port =====

This is the destination target port number. The packet will be forwarded from 22001 to 22 on the $hostname

=== OpenVPN Service ===

This is the most generic config available. It does nothing more then opening port(s) defined for our openvpn service in <code>/etc/awall/private/custom-services.json</code>

<pre>
{

"description": "Allow local OpenVPN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "openvpn",
"action": "accept"
}
]
}

</pre>

=== Allow ping on WAN ===

Allow rate-limited ping on WAN. Which has the same kind of flow limit as our previous SSH policy.

<pre>
{

"description": "Allow rate-limited ping on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ping",
"action": "accept",
"flow-limit": { "count": 10, "interval": 6 }
}
]
}
</pre>

== Using aliases and custom services ==

=== Aliases ===

To make life easier when your firewall rules increase, it can be nice to map specific hosts to names.
Awall supports something called [https://github.com/alpinelinux/awall#variable-expansion variable expansion] which is a mapping between a value and a variable.
When you have many devices behind your firewall/router, your policies can be harder to read. Also when one of your devices IP address change you will have to update all of your policies.
With awalls variables you can assign the ip address of a device to a variable name. Edit the following file: <code>/etc/awall/private/aliases.json</code>
<pre>
{
"description": "Hostname aliases",

"variable": {
"PRINTER": "192.168.1.1",
"SERVER": "192.168.1.2"
}

}
</pre>

Look in the example above where $SERVER is used to forward port 22001 to port 22.

NOTE: You are not limited to assigning only IP addresses to variables. You can use it however you like. More information can be found in the awall manual.

=== Custom services ===

Awall includes a predefined list of [https://github.com/alpinelinux/awall/blob/master/json/services.json services]. If the service you try to define in your policy does not exist in awalls services list you can define services yourself.

Create the file: <code>/etc/awall/private/custom-services.json</code>

<pre>
{
"service": {

"mqtt": [
{ "proto": "udp", "port": 1883 },
{ "proto": "tcp", "port": 1883 }
],

"openvpn": [
{ "proto": "udp", "port": 1194 },
{ "proto": "tcp", "port": 1194 }
]

}
}
</pre>

NOTE: although you are free to name your policy files however you want, you cannot name this file <code>services.json</code> because this policy name is already in use by the included services.json of awall.

== Using our policies ==

You should now have two directories in your awall config directory named optional and private with multiple json files. The biggest difference between these two directories is the ability to enable and disable policies located in the optional directory. When you enable a policy by using <code>awall enable policy-name</code> awall will generate a symlink in your awall config directory and will automatically load them when you activate the firewall. To be able to also use the files in the private directory we will need to include them in one of our optional policies. You can name the file however you like as long it doesn't conflict with existing policies names (including the ones in private directory and awall's system policies). Example names would be hostname.json main.json firewall.json. For this example we will use main.json.

Create the file: <code>/etc/awall/optional/main.json</code>
<pre>
{
"description": "Main firewall",

"import": [ "base", "aliases", "custom-services" ]

}
</pre>

Contents of your awall directory:
<pre>
awall
│
├── optional
│   ├── main.json
│ ├── openvpn.json
│   ├── ssh-to-hostname.json
│   └── ssh.json
└── private
   ├── aliases.json
   ├── base.json
   └── custom-services.json
</pre>

=== Enabling optional policies ===

Lets enable our created policies. First we list them by running <code>awall list</code> which would show something like:
<pre>
openvpn disabled Allow local OpenVPN
main disabled Main firewall
ping disabled Allow rate-limited ping on WAN
ssh disabled Allow rate-limited SSH on WAN
ssh-to-hostname disabled Forward SSH to hostname
</pre>

Each of these needs to be enabled:
<pre>
awall enable openvpn
awall enable main
awall enable ping
awall enable ssh
awall enable ssh-to-hostname
</pre>

The contents of your awall directory should now look like:
<pre>
awall/
├── main.json -> ./optional/main.json
├── openvpn.json -> ./optional/openvpn.json
├── optional
│   ├── main.json
│   ├── openvpn.json
│   ├── ping.json
│   ├── ssh-to-hostname.json
│   └── ssh.json
├── ping.json -> ./optional/ping.json
├── private
│   ├── aliases.json
│   ├── base.json
│   └── custom-services.json
├── ssh-to-hostname.json -> ./optional/ssh-to-hostname.json
└── ssh.json -> ./optional/ssh.json

2 directories, 13 files
</pre>

=== Testing policies ===

<code>awall translate --verify</code>

if everything goes well the output should be null.

=== Activating the firewall ===

Now that all our policies are verified for proper json we can activate it.

<code>awall activate</code>

This will load the firewall rules and show you a message to confirm. If by accident you made a mistake and lock yourself out you just have to wait for awall to disable itself again.

== Finishing up ==

=== Activating firewall rules at boot ===

When awall has been properly activated it will generate a file with all iptables rules which iptables will read when its is started via openrc.
Make sure you have added iptables to an openrc runlevel.

<code>rc-update add iptables</code>

=== Allow IPv4 forwarding ===

To allow iptables to forward packets from one zone to the other we need to enable this at the iptables level.

==== On the fly ====

To enable it on the fly:
<code>sysctl -w net.ipv4.ip_forward=1</code>

==== Enable within iptables tools (at boot) ====

Add the following to:
<code>/etc/conf.d/iptables</code>
<pre>
# Enable/disable IPv4 forwarding with the rules
IPFORWARD="yes"
</pre>

= See also =
* [[How-To Alpine Wall]]

[[Category:Security]]