Alpine Linux - User contributions [en]

ACF

2022-02-09T09:31:46Z

Jwatt: Propose deletion

#REDIRECT [[Alpine_Configuration_Framework_Design]]

([https://wiki.alpinelinux.org/w/index.php?title=Special%3AWhatLinksHere&target=ACF&namespace= Nothing links to this page])

{{Delete|Nothing links to this page}}

Stream a DV-camera using vlc

2022-02-09T09:30:18Z

Jwatt: Link directly to target page rather than going through redirect

{{draft}}
In this howto we are going to stream the video coming from a DV-camera connected through ie1394 (firewire). 
vlc is used to stream the content. 
We will be using h264 and AAC to transcode the stream ''(should be fairly easy to change to whatever suits your needs)''.

= Setup Alpine =
== Initial Setup ==
Follow [[Installing_Alpine]] to setup Alpine Linux.

== Install programs ==
{{Cmd| apk add vlc-daemon vlc-dev }}
{{note|If you intend to use a desktop environment with vlc you will need to install {{pkg|vlc-qt}} in order to get that working. {{pkg|vlc-dev}} or {{pkg|vlc}} package does not contain the graphical part of vlc ''(menus etc.)''.}}
{{todo| I haven't figured out why vlc-dev is needed. Manually adding all vlc-dev dependencies does not work. 
The 'require vlc-dev' thing is reported at http://bugs.alpinelinux.org/issues/1051 and might be solved soon ''(or 'vlc-dev' really is needed as a dependency)''.}}

== Using ACF to control vlc ==
{{tip|A easy way to control vlc-daemon would be through [[Alpine Configuration Framework Design|ACF]]. Consider following these simple steps. 
But as it is ''optional'' you could just skip this [[Alpine Configuration Framework Design|ACF]] section.}}
Setup/install acf ''(unless it's not already done)''.
{{cmd| setup-acf}}
Install acf-package for vlc
{{cmd| apk add acf-vlc-daemon}}
We won't describe in this tutorial how you would use [[Alpine Configuration Framework Design|ACF]] to control vlc-daemon ''(basically because it's so simple it does not need any describing)''. 
If you installed [[Alpine Configuration Framework Design|ACF]], just browse <nowiki>https://ip.of.your.box</nowiki> and you would from this tutorial understand what to do. 

= Configure vlc =
Configuration is done by modifying '/etc/conf.d/vlc'. 
Here comes the actual configuration that makes vlc stream the DV-camera.
<pre>
###############
BITRATE=500
XRES=720
YRES=576

###############
# Chose one of the following 'preset' values depending on how fast your CPU is:
# ultrafast,superfast,veryfast,faster,fast,medium,slow,slower,veryslow,placebo
TVIDEO="venc=x264{preset=ultrafast,vbv-maxrate=${BITRATE},vbv-bufsize=256,keyint=250,min-keyint=25},vcodec=h264,vb=${BITRATE},scale=1,width=${XRES},height=${YRES}"
TAUDIO="acodec=mp4a,ab=96,channels=2,samplerate=44100"
TMISC="deinterlace,audio-sync"

###############
TRANSPORT="std{access=http,mux=ts,dst=:8080}"

VLC_OPTS="--daemon -I dummy dv:///dev/fw0 --rawdv-hurry-up --sout-keep --sout-transcode-audio-sync \
--file-logging --logfile /var/log/vlc/vlc.log \
--sout #transcode{$TVIDEO,$TAUDIO,$TMISC}:$TRANSPORT"
</pre>

= Start it up =
== Prepare the hardware ==
Here comes the hardest part in this tutorial... Attach the DV-camera to your ie1394/firewire port. 
Well... that wasn't too hard! :-)

== Manual start ==
Start vlc-daemon either from terminal:
{{cmd|/etc/init.d/vlc start}}
or using ACF and just klick [Start].

== Make it start at next reboot ==
You might want to make it automatically start at next reboot
{{cmd|rc-update add vlc-daemon default}}

== Debug ==
In case something goes wrong, consider looking at the logfiles.
{{cmd|less -I /var/log/vlc/vlc.log}}
If you don't find any useful information you could add verbosity by adding '-v' or '-vv' to /etc/conf.d/vlc and restart vlc ''(you would need to restart vlc-daemon to see more information in the logs)''.

[[Category:Multimedia]]

APKBUILD examples:ACF

2022-02-09T09:28:32Z

Jwatt: Link directly to target page rather than going through redirect

[[Alpine Configuration Framework Design|ACF]] packages only needs a package() section.

<pre>
package() {
cd "$srcdir/$pkgname-$pkgver"
make DESTDIR="$pkgdir" install
}
</pre>

[[Category:Development]] [[Category:ACF]]

Alpine Configuration Framework Design

2022-02-09T09:26:21Z

Jwatt: Remove self references ('ACF' is a redirect back to this page)

= Alpine Configuration Framework =

The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine Linux device. The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "webmin".

== Why Haserl + Lua ==

Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.

A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that [http://www.lua.org Lua] has the following advantages:

*It is small (typically ~200KB of compiled code)
*It compiles and runs much faster than [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl] or [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
*It provides a "normal" scripting language with [http://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, [[awk]], etc.

Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.

== Why ACF is MVC ==

The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:

*'''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
*'''View''' - code that formats data for output
*'''Controller''' - code that glues the two together

Note the lack of words like: HTML, XML, OO, AJAX, etc. The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.

The flow of a single transaction is:

start -> execute requested function in '''controller''', optionally reading/writing a file using functions in the '''model''' -> execute the '''view''' to format the output -> end

''Every'' transaction follows this pattern. For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model. The presentation layer should be last on the priority list.

Of course, as with all MVC designs, the ACF MVC design is not quite 'pure' MVC and has evolved over time. Most of the '''controller''' functionality is handled by the framework code. The framework code will also automatically generate views for HTML, JSON, and a few other viewtypes if no '''view''' is defined. Also, many '''model''' functions are implemented in helper libraries. We have attempted to make it as easy as possible to develop new ACF modules.

For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at [http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf http://www.cs.usfcs.edu] or the [[Media:Mvc.templates.pdf|local copy]] of the pdf.

= Starting ACF =
Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF:
{{cmd|setup-acf}}
''(This script will install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages.)'' 

To view ACF, simply browse to your machine https://<hostname>/

See also [[Managing ACF|Managing Your ACF Installation]]

{{tip|Alternately, you can manually install ACF and your web server. The two critical ACF packages are acf-core and acf-alpine-baselayout. The ACF packages will install to /usr/share/acf. You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.}}

{{Warning| In Alpine Linux 1.8, the system includes two default users: ''alpine'' and ''foo''. 'alpine' is given ADMIN rights and 'foo' is given USER rights. The default password for both users is ''test123''. '''Replace the default users as soon as possible.''' 
As of 1.9 you will get prompted for a password for the 'root' account so this is no issue for newer Alpine Linux versions.}}

= ACF Developer's Guides =

#[[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
#[[ACF mvc.lua example|mvc.lua example]] - build a simple (command-line) application
#[[ACF acf www-controller.lua reference|acf www-controller reference]] - ACF www application functions
#[[ACF acf www example|acf www-controller example]] - webify the above examples
#[[ACF how to write]] - Step by step howto for writing ACF modules
#[[ACF core principles]] - Things that are standard across the application
#[[LPOSIX]] - Documentation for the Lua Posix functions
#[[ACF Libraries]] - Document the libraries and common functions
#[[Writing ACF Views]] - Guide for writing a view
#[[Writing ACF Controllers]] - Guide for writing a controller
#[[Writing ACF Models]] - Guide for writing a model

== Other useful links ==

#[http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
#[http://www.lua.org/pil/ Programming in Lua (first edition)]
#[[Managing ACF]]

= ACF Layout =

ACF has support for multiple skins. Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.

== How to contribute ==

First, download ACF using git or installing available ACF modules using 'apk add'. Easiest is if you download the latest Alpine Linux ISO, boot a box from the ISO and then run 'setup-alpine' and 'setup-acf'. That way you get a running environment fast and easy! Some example skins are available:

*/usr/share/acf/www/skins/alps/
*/usr/share/acf/www/skins/cloud/
*/usr/share/acf/www/skins/ice/
*/usr/share/acf/www/skins/snow/
*/usr/share/acf/www/skins/wik/

Make a new skin folder.

mkdir -p /etc/acf/skins/myskin

Create a css file called as the folder.

touch /etc/acf/skins/myskin/myskin.css

Now you can start editing your myskin.css. If you have ACF running on the computer, you can browse to https://<hostname>/cgi-bin/acf/acf-util/skins/read and switch to your new skin (called myskin) and see the results of your changes.

Pack your myskin folder, containing your css file (and images, if there are any). Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [http://wiki.alpinelinux.org/w/index.php?title=Mailing_lists subscribe] before sending your patch)''

= ACF Packages =

Look at [http://wiki.alpinelinux.org/w/index.php?title=ACF_packages ACF packages] to see available ACF modules and their status.

[[Category:ACF]] [[Category:Lua]]

Alpine Linux On The Command Line

2022-02-09T09:23:35Z

Jwatt: Propose deletion

#REDIRECT [[Alpine Linux package management]]

([https://wiki.alpinelinux.org/w/index.php?title=Special%3AWhatLinksHere&target=Alpine%20Linux%20On%20The%20Command%20Line&namespace= Nothing links to this page])

{{Delete|Nothing links to this page}}

Install to disk

2022-02-09T09:14:16Z

Jwatt: Fix link

= If using Alpine Linux 2.2.3 or later =

{{Warning|This will erase '''everything''' on your machine's harddisk. Don't blame me if someone sues you for this, your cat dies etc. You are warned.}}

The following is meant to be an absolute newbie guide

* [[Burning ISOs|Burn the Alpine ISO image to a CD]]
* Put the CD into the new computer and turn on the power. Make sure the computer is capable to boot from a CD. Your manual for the computer or the BIOS can help.
* Wait for the text '''login:''' to appear, type '''root''' and press enter.
* Run the '''setup-alpine''' script
** Choose your keyboard layout. If you don't know your keyboard layout choose '''us'''. Here '''us''' was chosen.
*** Then I chose the '''us''' variant.
** Host name, which will be the name of your computer, you can just press enter if you want to use the default name
** Choose your network card, most people can just go with the default (press enter)
*** Most people will use DHCP, so press enter again, or you can enter in your static IP address
*** You will be asked if you want to do any manual network configuration, press enter for no
** Type in your root password twice.
** Choose a time zone, you can get a list by pressing '''?'''. If you want a sub zone, e.g. Africa, type in Africa and press enter, '''?''' will give you a list of sub zones in Africa.
** Press '''f''' to choose the fastest mirror.
** Choose an SSH server, this allows you to remotely manage your machine. OpenSSH is what the big distro's use, Dropbear is a tiny SSH replacement. Choose '''none''' for best security.
** Choose an NTP client, this keeps your machine's time accurate using an Internet time server. Openntpd is what the big distro's use, while Chrony is a tiny replacement.
** Choose a disk you want to install Alpine onto, as an example, '''sda''' is the first disk in your computer.
*** Now choose how you would like to use it, for this guide, choose '''sys''', this will install the entire OS onto your hard drive
*** You are given a final chance to back out, type in '''Y''' to continue
* The installation is now complete and you will be asked to reboot. Type in '''reboot''' and press enter
Take out the CD, and your computer should boot into Alpine using your hard drive.

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[OpenRC]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''
* [[Tutorials and Howtos]] ''(Various tutorials, including how to setup a [[XFCE Setup|XFCE desktop]])''

[[Category:Installation]]

= If using Alpine Linux 2.2.2 or earlier =

A number of steps are nowadays included in the setup-disk and setup-lbu scripts, which are invoked by setup-alpine. But in these older systems, these steps have to be performed manually.

Run <code>setup-alpine</code> to configure the keyboard, hostname and networking.
{{Cmd|setup-alpine}}

Now for the manual steps. Install needed programs for the setup:
{{Cmd|apk add e2fsprogs syslinux mkinitfs}}

Create partitions with <code>fdisk</code>.
{{Cmd|fdisk /dev/sda}}

Let's say you have 2 partitions: {{Path|/dev/sda1}} as "Linux" (type 83) and {{Path|/dev/sda2}} as "linux swap" (type 82). The partition containing {{Path|/boot}}---here, {{Path|/dev/sda1}}---must be marked bootable (command "a" within <code>fdisk</code>).

Next, create your filesystem(s) and swap:

{{Cmd|mkfs.ext4 /dev/sda1
mkswap /dev/sda2}}

Mount the filesystem:
{{Cmd|mount -t ext4 /dev/sda1 /mnt}}

Clone the current running config created by <code>setup-alpine</code> (hostname, networking root password):
{{Cmd|<nowiki>lbu package - | tar -C /mnt -zxf -</nowiki>}}

Install base packages on the mounted disk:
{{Cmd|<nowiki>apk add --root=/mnt --initdb $(cat /etc/apk/world)</nowiki>}}

Append the / and swap to {{Path|/etc/fstab}}:
{{Cmd|echo -e "/dev/sda1 / ext4 defaults 1 1" >> /mnt/etc/fstab
echo -e "/dev/sda2 none swap sw 0 0" >> /mnt/etc/fstab}}

Configure the boot loader, <code>extlinux</code>. We use the provided {{Path|syslinux.cfg}} as base.
{{Cmd|cp /media/cdrom/syslinux.cfg /mnt/boot/extlinux.conf
vi /mnt/boot/extlinux.conf}}

It should contain something like:
timeout 20
prompt 1
default grsec
label grsec
kernel /boot/grsec
append initrd=/boot/grsec.gz root=/dev/sda1 modules=ext4 quiet

Install the [[Bootloaders|bootloader]] on your {{Path|/boot}} partition:
{{Cmd|extlinux -i /mnt/boot}}

Install the early-stage bootloader in the disk's MBR (note that it's {{Path|/dev/sda}} not {{Path|/dev/sda1}}!)
{{Cmd|<nowiki>dd if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}

This also works:
{{Cmd|cat /usr/share/syslinux/mbr.bin > /dev/sda}}

Unmount, remove cdrom, and reboot. (If you can't eject, just remove it manually as the machine reboots)
{{Cmd|umount /mnt
umount /.modloop
eject
reboot}}

In recent versions of Alpine, the second line can be accomplished by <code>rc-service modloop stop</code>. (See [[FAQ#How_do_I_remove_the_CDROM.3F|this FAQ entry]]).

After reboot, you should be able to log in as root with the password you created in <code>setup-alpine</code>.

[[Category:Installation]]

XFCE Setup

2022-02-09T09:09:01Z

Jwatt: Avoid double redirect

#REDIRECT [[Xfce]]

Desktop-notes

2022-02-09T09:08:29Z

Jwatt: Avoid double redirect

#REDIRECT [[Xfce]]

SLiM

2022-02-09T09:08:03Z

Jwatt: Fix link

{{Delete|The project hasnt had any commits since 2013 and its likely not working anymore}}

 

{{Warning|The SLiM project appears to have been abandoned since 2013, although the [http://slim.berlios.de/ project homepage] is online. Also: https://github.com/iwamatsu/slim}}

 

[http://slim.berlios.de/index.php SLiM] is a Simple Login Manager (also known as a display manager) which is lightweight and simple to configure.

== Install ==

Simply add the {{Pkg|slim}} package with:
{{Cmd|apk add slim}}
I should imagine you'd also want some kind of desktop installed too, like [[Gnome Setup|Gnome]] or [[XFCE Setup|XFCE]]

== Configure & Test ==

The SLiM configuration file is at <code>/etc/slim.conf</code> and it is heavily commented, so I'll not add any info about it here unless asked to (in the discussion function for instance). Before making any changes it is recommended to backup the default configuration file with:
{{Cmd|cp /etc/slim.conf /etc/slim.conf.original}}

Then you can modify <code>/etc/slim.conf</code> and easily copy the default configuration back if you run into trouble:
{{Cmd|cp /etc/slim.conf.original /etc/slim.conf}}

To immediately test slim, do {{Cmd|rc-service slim start}} and you should be presented with a login screen, branded for Alpine linux!

Login with your normal user credentials (avoid using a desktop as root) and you should reach your desktop.

Once you've tested it works, start SLiM at the default runlevel:
{{Cmd|rc-update add slim}}

Note: You should disable any other display manager you have running to prevent them both launching. For example, to prevent lxdm from starting at boot use:
{{Cmd|rc-update del lxdm}}

== Extra Login Commands ==
When on the SLiM login screen, you can use:
* <code>exit</code> as a username to return to a shell prompt
* <code>reboot</code> as a username and the root password to reboot the machine
* <code>halt</code> as a username and the root password to power down the machine

== Troubleshooting ==

If you are using a .xinitrc file (usually located at <code>~/.xinitrc</code>, slim will read from this and you will need to ensure you have a line to execute your desktop environment. This is usually the last line of the file. For example:
<pre>....
exec startxfce4
</pre>
if you are using an [[Xfce]], or:
<pre>....
exec gnome-session
</pre>
if using [[Gnome]].

If you don't do this, or you make a mistake with your typing, you'll probably get an error like <code>failed to execute login command</code>

== Themes ==

Simply add the {{Pkg|slim-theme}} package with:
{{Cmd|apk add slim-themes}}

All theme which are available on your system are located at <code>/usr/share/slim/themes</code>
{{Cmd|ls /usr/share/slim/themes}}

You need to modify <code>/etc/slim.conf</code> to change the theme:
{{Cmd|sudo vi /etc/slim.conf}}

Search for <code>current_theme</code> and choose one of the available themes.

== Further Information ==

* [http://slim.berlios.de/index.php SLiM Homepage]
* [http://slim.berlios.de/manual.php SLiM Manual]
* [https://wiki.archlinux.org/index.php/SLiM Arch Linux wiki entry]

[[Category:Desktop]]

Tutorials and Howtos

2022-02-09T09:07:43Z

Jwatt: Fix link

{{Todo|This material needs to be re-organized .. as '''Howtos are smaller articles''' and '''tutorials are more detailed document''' both need to be reordered as independent sections }}

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}
'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''The tutorials are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions.

'''IMPORTANT:''' contributions on those pages must be complete articles as well as requesting topics to be covered, don't override already made contributions. If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].

{{Clear}}

=== Postinstall ===

* [[Post installation|Post installation notes]]

==== Postinstall: desktops and applications ====

* [[Desktop environments and Window managers]] (overall information only)
** [[Xfce]]
** [[LXQt]]
** [[Openbox]]
** [[MATE]]
* [[Alpine and UEFI|Alpine and UEFI Support Status and related topics]]

==== Developers: compilers, IDEs and tools ====

* [[Alpine newbie developer]]
** [[Alpine newbie developer: gitea|Alpine newbie developer: Git management web frontend gitea]]
** [[Alpine newbie developer: full stack web]]

==== Servers: deploy in production ====

* [[Alpine production deploy]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
** [[Production DataBases : mysql|Production database: MySql]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎]]
* Alpine production monitoring
** [[Cacti: traffic analysis and monitoring network]]
** [[Zabbix|Zabbix - the professional complete manager]]

== Storage ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)'' 
** [[Back Up a Flash Memory Installation]] 
** [[Manually editing a existing apkovl]]

* [[Setting up disks manually]] 
* [[Setting up a software RAID array]]

* [[Raid Administration]]
* [[Setting up encrypted volumes with LUKS]]
* [[Setting up LVM on LUKS]]
* [[Setting up Logical Volumes with LVM]]
** [[Setting up LVM on GPT-labeled disks]]
** [[Installing on GPT LVM]]
* [[Filesystems|Formatting HD/Floppy/Other]] 

* [[Setting up iSCSI]]
** [[iSCSI Raid and Clustered File Systems]]
* [[Setting up NBD]]
* [[Setting up ZFS on LUKS]]
* [[Setting up ZFS with native encryption]]
* [[High performance SCST iSCSI Target on Linux software Raid]] ''(deprecated)'' 
* [[Linux iSCSI Target (TCM)]]
* [[Disk Replication with DRBD]] 

* [[Burning ISOs]] 
* [[Partitioning and Bootmanagers]]
* [[Migrating data]]
* [[Create a bootable SDHC from a Mac]]
* [[Alpine on ARM]]

== Networking ==

* [[Configure Networking]]
* [[Connecting to a wireless access point]]
* [[Bonding]]
* [[Vlan]]
* [[Bridge]]
* [[Bridge wlan0 to eth0]]
* [[OpenVSwitch]]
* [[How to configure static routes]]
* [[Configure a Wireguard interface (wg)]]

* [[Alpine Wall]] - [[How-To Alpine Wall]] - [[Alpine Wall User's Guide]] ''(a new firewall management framework)''

* [[PXE boot]]

* [[Using serial modem]]
* [[Using HSDPA modem]]
* [[Setting up Satellite Internet Connection]]
* [[Using Alpine on Windows domain with IPSEC isolation]]

* [[Setting up a SSH server]] ''(Using SSH is the preferred way to administer your box remotely)'' 
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''
* [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* [[How to set up Alpine as a wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[Setting up a OpenVPN server with Alpine]] ''(Allowing single users or devices to remotely connect to your network)''

* [[Experiences with OpenVPN-client on ALIX.2D3]] 

* [[Generating SSL certs with ACF]] 
* [[Setting up unbound DNS server]]
* [[Setting up nsd DNS server]]
* [[TinyDNS Format]]
* [[Fault Tolerant Routing with Alpine Linux]] 
* [[Freeradius Active Directory Integration]]
* [[Multi_ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[OwnCloud]] ''(Installing OwnCloud)''

* [[Seafile: setting up your own private cloud]]

* [[GNUnet]]

== Post-Install ==


* [[Setting up a new user]]
* [[Enable Community Repository]] ''(Providing additional packages)''
* [[Alpine Linux package management|Package Management (apk)]] ''(How to add/remove packages on your Alpine)''

** [[Comparison with other distros]]
* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]] 
** [[Manually editing a existing apkovl]]
* [[Alpine Linux Init System|Init System (OpenRC)]] ''(Configure a service to automatically boot at next reboot)''
** [[Multiple Instances of Services]]

* [[Alpine setup scripts#setup-xorg-base|Setting up Xorg]]
* [[Upgrading Alpine]]


* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''
* [[setup-acf]] ''(Configures ACF (webconfiguration) so you can manage your box through https)''
* [[Changing passwords for ACF|Changing passwords]]
* [[Ansible]] ''(Configuration management)''

* [[Enable Serial Console on Boot]]

* [[How to get regular stuff working]] ''some notes on need-to-know topics''
* [[Installing Oracle Java]]
* [[Rsnapshot|Setting up periodic backups with <samp>rsnapshot</samp>]]

== Virtualization==

* [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
* [[Xen Dom0 on USB or SD]]
* [[Create Alpine Linux PV DomU]]
* [[Xen PCI Passthrough]]
* [[Xen LiveCD]]
* [[QEMU]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[Docker]]
* [[Install Alpine on VirtualBox]]
* [[Install Alpine on VMWare]]

== Desktop Environment ==

* [[AwesomeWM]]
* [[dwm]]
* [[EyeOS]] ''(Cloud Computing Desktop)''
* [[Gnome]]
* [[KDE]]
* [[MATE]]
* [[Oneye]] ''(Cloud Computing Desktop - Dropbox Alternative)''
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Remote Desktop Server]]
* [[River]]
* [[Suspend on LID close]]
* [[Sway]]
* [[Xfce]]
* [[Sound Setup]]
* [[PipeWire]]
* [[Printer Setup]]
* [[Default applications]]

== Raspberry Pi ==

* [[Raspberry Pi|Raspberry Pi (Installation)]]
* [[Raspberry Pi - Headless Installation]]
* [[Classic install or sys mode on Raspberry Pi]]
* [[RPI Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Linux Router with VPN on a Raspberry Pi]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi Zero W - Installation]]
* [[Raspberry Pi Bluetooth Speaker]]

== PowerPC ==

* [[Ppc64le|Powerpc64le (Installation)]]

== IBM Z (IBM z Systems) ==

* [[s390x|s390x (Installation)]]

== Applications ==

=== Telephony ===
* [[Setting up Zaptel/Asterisk on Alpine]]
** [[Setting up Streaming an Asterisk Channel]]
* [[Freepbx on Alpine Linux]]
* [[FreePBX_V3]] ''(FreeSWITCH, Asterisk GUI web acces tool)''
* [[2600hz]] ''(FreeSWITCH, Asterisk GUI web access tool)''
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== Mail ===
* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
** [[Hosting Web/Email services on Alpine]]
* [[ISP Mail Server HowTo]] 
** [[ISP Mail Server Upgrade 2.x]]
** [[ISP Mail Server 2.x HowTo]] ''(Beta, please test)''
** [[ISP Mail Server 3.x HowTo]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* [[Protecting your email server with Alpine]]
* [[Setting up clamsmtp]]
* [[Setting up dovecot with imap and ssl]]
* [[relay email to gmail (msmtp, mailx, sendmail]]

=== HTTP ===
* [[Lighttpd]]
** [[Lighttpd Https access]]
** [[Setting Up Lighttpd with PHP]]
** [[Setting Up Lighttpd With FastCGI]]
* [[Cherokee]]
* [[Nginx]]
** [[Nginx_with_PHP#Nginx_with_PHP|Nginx with PHP]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]

* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)'' 

* [[Setting up Transparent Squid Proxy]] 
** [[SqStat]] ''(Script to look at active squid users connections)''
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[Setting up Explicit Squid Proxy]]

* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[DokuWiki]]
* [[Darkhttpd]]
* [[Tomcat]]
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''

=== Other Servers ===
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''

* [[Setting up a nfs-server]]
* [[Setting up a samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc]] ''(Active Directory compatible domain controller)''
* [[Phpizabi]] ''(Social Networking Platform)''
* [[Statusnet]] ''(Microblogging Platform)''
* [[Pastebin]] ''(Pastebin software application)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system)''
* [[Request-Tracker]] ''(Ticket system)''
* [[OsTicket]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''

* [[Alpine_newbie_developer: gitea|Setting up Git management web frontend gitea]]
* [[Cgit]]
** [[Setting up a git repository server with gitolite and cgit]] 
* [[Roundcube]] ''(Webmail system)''
* [[Glpi]] ''(Manage inventory of technical resources)''

* [[How to setup a Alpine Linux mirror]]
* [[Cups]]
* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''
* [[How To Setup Your Own IRC Network]] ''(Using {{Pkg|charybdis}} and {{Pkg|atheme-iris}})''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[Chrony and GPSD | Using chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Sending SMS using gnokii]]
* [[IPTV How To|Internet Protocol television (IPTV)]]
* [[UniFi_Controller]]
* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Odoo]]

=== Monitoring ===
* Setting up [[collectd]]
* [[Traffic monitoring]] 
* [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Setting up monitoring using rrdtool (and rrdcollect)]]
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[LTTng]] ''(Kernel and userspace tracing)''
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting up Smokeping|Smokeping]] ''(Network latency monitoring)'' 
** [[Setting up MRTG and Smokeping to Monitor Bandwidth Usage and Network Latency]]
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance)'' 
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 

* [[IP Accounting]] 
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''

* [[Piwik]] ''(A real time web analytics software program)''
* [[Awstats]] ''(Free log file analyzer)''
* [[Intrusion Detection using Snort]]
** [[Intrusion Detection using Snort, Sguil, Barnyard and more]]
* [[Dglog]] ''(Log analyzer for the web content filter DansGuardian)''

* [[Webmin]] ''(A web-based interface for Linux system)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Linfo]]

* [[Setting up lm_sensors]]

* [[ZoneMinder video camera security and surveillance]]

== Misc ==

* [[:Category:Shell]]
* [[:Category:Programming]]
* [[Running glibc programs]]
* [[:Category:Drivers]]
* [[:Category:Multimedia]]
* [[Kernel Modesetting]]
* [[CPU frequency scaling]]

== Complete Solutions ==
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [https://codeberg.org/AVG7/alpine-sway-x86_64 DIY Live-USB-Stick with Sway]
* [[Alpine on the Aopen Chromebase or Chromebox Mini with Mainline Kernel]]
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[High performance SCST iSCSI Target on Linux software Raid]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[Experiences with OpenVPN-client on ALIX.2D3]]
* [[Building a cloud with Alpine Linux]]

* [[ISP Mail Server HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-serivce ISP mail server)''
** [[ISP Mail Server Upgrade 2.x]]
** [[ISP Mail Server 2.x HowTo]] ''(Beta, please test)''
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small_Office_Services]]



== Newbies ==

* [[Alpine_newbie]] (for overall information in funny sections)

[[Category:System_Administration]]
[[Category:Installation]]

Create a Bootable Device

2022-01-26T23:42:05Z

Jwatt:

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.

=== Copying ISO/tarball contents to a USB stick ===

This method is written for copying files from an Alpine ISO file but also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

# Install some prerequisites. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)
#: {{Cmd|apk add dosfstools apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file device file] name of the USB stick that Alpine Linux is to be installed to:
#: {{Warning | BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK! }}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|umount -q $mydev?}}
# Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
o
n
p
1
2048
-0
t
0c
a
w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix executable boot code] into the bootstrap code area of the MBR boot sector (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# Install the syslinux bootloader files onto the FAT32 filesystem (ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine {{Path|.tar.gz}} tarball instead of copying {{Path|/media/cdrom}}, set <code>$alpinetarball</code> to the path to the tarball and replace the 'cp' line with: <code>tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"</code>):
#: {{Cmd|<nowiki>mydevname=$(basename $mydev)1
mkdir -p /media/$mydevname
mount -t vfat ${mydev}1 /media/$mydevname
cp -aT /media/cdrom /media/$mydevname # -T to copy hidden files
umount /media/$mydevname</nowiki>}}
# (''Optional'') Remove any .apkovl overlay files that were transferred as part of the copy process. Do this if you want an unmodified, vanilla install.
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]

Create a Bootable Device

2022-01-26T23:23:20Z

Jwatt:

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.

=== Copying ISO/tarball contents to a USB stick ===

This method is written for copying files from an Alpine ISO file but also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

# Install some prerequisites. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)
#: {{Cmd|apk add dosfstools apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file device file] name of the USB stick that Alpine Linux is to be installed to:
#: {{Warning | BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK! }}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|umount -q $mydev?}}
# Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
o
n
p
1
2048
-0
t
0c
a
w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix executable boot code] into the MBR table (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# Install the syslinux bootloader files onto the FAT32 filesystem (ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine {{Path|.tar.gz}} tarball instead of copying {{Path|/media/cdrom}}, set <code>$alpinetarball</code> to the path to the tarball and replace the 'cp' line with: <code>tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"</code>):
#: {{Cmd|<nowiki>mydevname=$(basename $mydev)1
mkdir -p /media/$mydevname
mount -t vfat ${mydev}1 /media/$mydevname
cp -aT /media/cdrom /media/$mydevname # -T to copy hidden files
umount /media/$mydevname</nowiki>}}
# (''Optional'') Remove any .apkovl overlay files that were transferred as part of the copy process. Do this if you want an unmodified, vanilla install.
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]

Create a Bootable Device

2022-01-26T23:16:22Z

Jwatt:

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.

=== Copying ISO/tarball contents to a USB stick ===

This method is written for copying files from an Alpine ISO file but also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

# Install some prerequisites. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)
#: {{Cmd|apk add dosfstools apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file device file] name of the USB stick that Alpine Linux is to be installed to:
#: {{Warning | BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK! }}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|umount -q $mydev?}}
# Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
o
n
p
1
2048
-0
t
0c
a
w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix executable boot code] into the MBR table (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# Install the syslinux bootloader files onto the FAT32 filesystem (ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine {{Path|.tar.gz}} tarball instead of copying {{Path|/media/cdrom}}, set <code>$alpinetarball</code> to the path to the tarball and replace the 'cp' line with: <code>tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"</code>):
#: {{Cmd|<nowiki>mydevname=$(basename $mydev)1
mkdir -p /media/$mydevname
mount -t vfat ${mydev}1 /media/$mydevname
cp -aT /media/cdrom /media/$mydevname # -T to copy hidden files
umount /media/$mydevname</nowiki>}}
# (''Optional'') Remove any apkovl files that were transfered as part of the copy process. This should be done if you wish to have a fresh install. Replace sdU with your device name)
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]

Create a Bootable Device

2022-01-26T21:56:26Z

Jwatt: Rework the "Copy the Alpine files to the FAT32 filesystem" bullet point to be simpler

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.

=== Copy ISO content to USB stick as individual files ===

This method also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

# Install some prerequisites. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)
#: {{Cmd|apk add dosfstools apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file device file] name of the USB stick that Alpine Linux is to be installed to:
#: {{Warning | BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK! }}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|umount -q $mydev?}}
# Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
o
n
p
1
2048
-0
t
0c
a
w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix executable boot code] into the MBR table (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# Install the syslinux bootloader files onto the FAT32 filesystem (ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (to copy the contents of an Alpine {{Path|.tar.gz}} tarball instead of copying {{Path|/media/cdrom}}, set <code>$alpinetarball</code> to the path to the tarball and replace the 'cp' line with: <code>tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"</code>):
#: {{Cmd|<nowiki>mydevname=$(basename $mydev)1
mkdir -p /media/$mydevname
mount -t vfat ${mydev}1 /media/$mydevname
cp -aT /media/cdrom /media/$mydevname # -T to copy hidden files
umount /media/$mydevname</nowiki>}}
# (''Optional'') Remove any apkovl files that were transfered as part of the copy process. This should be done if you wish to have a fresh install. Replace sdU with your device name)
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]

Alpine configuration management scripts

2022-01-26T18:14:50Z

Jwatt: Tweak and add link to the intro text.

Feature descriptions for available Alpine Linux setup scripts ({{Path|/sbin/setup-*}}).

These scripts can be installed by using <code>apk</code> to install the <code>alpine-conf</code> package.

If you don't have an Alpine Linux install, you can find and examine the scripts in their [https://github.com/alpinelinux/alpine-conf git repository].

== setup-alpine ==

This is the main Alpine configuration and installation script.

The script interactively walks the user through executing several auxiliary <code>setup-*</code> scripts, in the order shown below.

The bracketed options represent example configuration choices, formatted as they may be supplied when manually calling the auxiliary setup scripts, or using a <code>setup-alpine</code> "answerfile" (see below).

# <code>setup-keymap</code> [us us]
# [[#setup-hostname|setup-hostname]] [-n alpine-test]
# [[#setup-interfaces|setup-interfaces]] [-i < interfaces-file]
# <code>/etc/init.d/networking --quiet start &</code>
# if none of the networking interfaces were configured using dhcp, then: <code>[[#setup-dns|setup-dns]]</code> [-d example.com -n "192.168.0.1 [...]"]
# set the root password
# if not in quick mode, then: <code>[[#setup-timezone|setup-timezone]]</code> [-z UTC | -z America/New_York | -p EST+5]
# enable the new hostname (<code>/etc/init.d/hostname --quiet restart</code>)
# add <code>networking</code> and <code>urandom</code> to the '''boot''' rc level, and <code>acpid</code> and <code>crond</code> to the '''default''' rc level, and start the '''boot''' and '''default''' rc services
# extract the fully-qualified domain name and hostname from {{Path|/etc/resolv.conf}} and <code>hostname</code>, and update {{Path|/etc/hosts}}
# <code>[[#setup-proxy|setup-proxy]]</code> [-q <nowiki>"http://webproxy:8080"</nowiki>], and activate proxy if it was configured
# <code>setup-apkrepos</code> [-r (to select a mirror randomly)]
# if not in quick mode, then: <code>[[#setup-sshd|setup-sshd]]</code> [-c openssh | dropbear | none]
# if not in quick mode, then: <code>setup-ntp</code> [-c chrony | openntpd | busybox | none]
# if not in quick mode, then: <code>DEFAULT_DISK=none</code> <code>[[#setup-disk|setup-disk]]</code> <code>-q</code> [-m data /dev/sda] (see [[Installation#Installation_Overview]] about the disk modes)
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-lbu</code> [/media/sdb1]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-apkcache</code> [/media/sdb1/cache | none]

<code>setup-alpine</code> itself accepts the following command-line switches

{{Define|-h|Shows the up-to-date usage help message.}}

{{Define|-a|Create an overlay file: this creates a temporary directory and saves its location in ROOT; however, the script doesn't export this variable so I think this feature isn't currently functional.}}
;-c <var>answerfile</var>
:Create a new "answerfile", with default choices. You can edit the file and then invoke <code>setup-alpine -f <var>answerfile</var></code>.
;-f <var>answerfile</var>
:Use an existing "answerfile", which may override some or all of the interactive prompts.
{{Define|-q|Run in "quick mode".}}

 

== setup-hostname ==

:<code>setup-hostname</code> [-h] [-n hostname]

Options:

'''-h''' <var>Show help</var>

'''-n''' <var>Specify hostname</var>

This script allows quick and easy setup of the system hostname by writing it to {{Path|/etc/hostname}}. The script prevents you from writing an invalid hostname (such as one that used invalid characters or starts with a '-' or is too long).
The script can be invoked manually or is called as part of the <code>setup-alpine</code> script.

 

== setup-interfaces ==
{{Cmd|setup-interfaces [-i < <var>interfaces-file</var>]}}

Note that the contents of <var>interfaces-file</var> has to be supplied as stdin, rather than naming the file as an additional argument. The contents should have the format of {{Path|/etc/network/interfaces}}, such as:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
hostname alpine-test

 

== setup-dns ==

:<code>setup-dns</code> [-h] [-d domain name] [-n name server]

Options:

'''-h''' <var>Show help</var>

'''-d''' <var>specify search domain name</var>

'''-n''' <var>name server IP</var>

The setup-dns script is stored in {{Path|/sbin/setup-dns}} and allows quick and simple setup of DNS servers (and a DNS search domain if required). Simply running <code>setup-dns</code> will allow interactive use of the script, or the options can be specified.

The information fed to this script is written to {{Path|/etc/resolv.conf}}

Example usage (with 192.168.0.1 being the local router/dns-forwarder): {{Cmd|setup-dns -d example.org -n 192.168.0.1}}

Example {{Path|/etc/resolv.conf}}:

search example.org
nameserver 192.168.0.1

It can be run manually but is also invoked in the <code>setup-alpine</code> script unless interfaces are configured for DHCP.

 

== setup-timezone ==
:<code>setup-timezone</code> [-z UTC | -z America/New_York | -p EST+5]

Can pre-select the timezone using either of these switches:

'''-z''' <var>subfolder of</var> {{Path|/usr/share/zoneinfo}}

'''-p''' <var>POSIX TZ format</var>

 

== setup-proxy ==
:<code>setup-proxy</code> [-hq] [PROXYURL]

Options:

'''-h''' <var>Show help</var>

'''-q''' <var>Quiet mode</var> prevents changes from taking effect until after reboot

This script requests the system proxy to use in the form <code>http://<proxyurl>:<port></code> for example:
<code><nowiki>http://10.0.0.1:8080</nowiki></code>

To set no system proxy use <code>none</code>.
This script exports the following environmental variables:

<code>http_proxy=$proxyurl</code>

<code>https_proxy=$proxyurl</code>

<code>ftp_proxy=$proxyurl</code>

where <code>$proxyurl</code> is the value input.
If <code>none</code> was chosen then the value it is set to a blank value (and so no proxy is used).

 

== setup-apkrepos ==
:<code>setup-apkrepos</code> [-fhr] [REPO...]

Setup <code>apk</code> repositories.

options:

'''-f''' <var>Detect and add fastest mirror</var>

'''-r''' <var>Add a random mirror and do not prompt</var>

'''-1''' <var>Add first mirror on the list (normally a CDN)</var>

This is run as part of the <code>setup-alpine</code> script.

 

== setup-sshd ==

:<code>setup-sshd</code> [-h] [-c choice of SSH daemon]

Options:

'''-h''' <var>Show help</var>

'''-c''' <var>SSH daemon</var> where SSH daemon can be one of the following:

<code>openssh</code> install the {{Pkg|openSSH}} daemon

<code>dropbear</code> install the {{Pkg|dropbear}} daemon

<code>none</code> Do not install an SSH daemon

Example usage: {{Cmd|setup-sshd -c dropbear}}

The setup-sshd script is stored in {{Path|/sbin/setup-sshd}} and allows quick and simple setup of either the OpenSSH or Dropbear SSH daemon & client.
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

 

== setup-ntp ==

''From [https://en.wikipedia.org/wiki/Network_Time_Protocol Wikipedia]'':

The '''Network Time Protocol (NTP)''' is a networking protocol for clock synchronization between computer systems over packet-switched, variable-latency data networks.

 

{{Cmd|usage: setup-ntp [-h] [-c choice of NTP daemon]

Setup NTP time synchronization

options:
-h Show this help
-c Choice of NTP daemon: busybox openntpd chrony none}}

<code>setup-ntp</code> script is stored in {{Path|/sbin/setup-ntp}} and allows quick and simple setup of the NTP client,
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

 

== setup-disk ==

:<code>DEFAULT_DISK=none setup-disk -q</code> [-m data | sys] [<var>mountpoint directory</var> | /dev/sda ...]

In "sys" mode, it's an installer, it permanently installs Alpine on the disk, in "data" mode, it provides a larger and persistent /var volume.

This script accepts the following command-line switches:

;-k <var>kernel flavor</var>
;-o <var>apkovl file</var>
:Restore system from <var>apkovl file</var>
;-m data | sys
:Don't prompt for installation mode. With '''-m data''', the supplied devices are formatted to use as a {{Path|/var}} volume.
{{Define|-r|Use RAID1 with a single disk (degraded mode)}}
{{Define|-L|Create and use volumes in a LVM group}}
;-s <var>swap size in MB</var>
:Use 0 to disable swap
{{Define|-q|Exit quietly if no disks are found}}
{{Define|-v|Verbose mode}}

The script also honors the following environment variables:

<code>BOOT_SIZE</code>
:Size of the boot partition in MB; defaults to 100. Only used if '''-m sys''' is specified or interactively selected.

<code>SWAP_SIZE</code>
:Size of the swap volume in MB; set to 0 to disable swap. If not specified, will default to twice RAM, up to 4096, but won't be more than 1/3 the size of the smallest disk, and if less than 64 will just be 0. Only used if '''-m sys''' is specified or interactively selected.

<code>ROOTFS</code>
:Filesystem to use for the / volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[Btrfs|btrfs]] xfs.

<code>BOOTFS</code>
:Filesystem to use for the /boot volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[Btrfs|btrfs]] xfs.

<code>VARFS</code>
:Filesystem to use for the /var volume; defaults to ext4. Only used if '''-m data''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 [[Btrfs|btrfs]] xfs.

<code>SYSROOT</code>
:Mountpoint to use when creating volumes and doing traditional disk install ('''-m sys'''). Defaults to {{Path|/mnt}}.

<code>MBR</code>
:Path of MBR binary code, defaults to {{Path|/usr/share/syslinux/mbr.bin}}.

<code>BOOTLOADER</code>
:Bootloader to use, defaults to syslinux. Supported bootloaders are: grub syslinux zipl.

<code>DISKLABEL</code>
:Disklabel to use, defaults to dos. Supported disklabels are: dos gpt eckd.



=== Partitioning ===

If you have complex partitioning needs, that go beyond above alpine-disk options, you can partition, format, and mount your volumes manually, and then just supply the root mountpoint to <code>setup-disk</code>. Doing so implicitly behaves as though '''-m sys''' had also been specified.

See [[Setting up disks manually]] for more information.

==== RAID ====
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device. The array will always be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_1 RAID1] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-0.90_Superblock_Format --metadata=0.90]) for the /boot volumes, but will be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_5 RAID5] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-1_Superblock_Format --metadata=1.2] for non-boot volumes when 3 or more devices are supplied.

If you instead want to build your RAID array manually, see [[Setting up a software RAID array]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.

==== LVM ====
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch. The group and volumes created by the script will have the following names:

* volume group: '''vg0'''
* swap volume: '''lv_swap''' (only created when swap size > 0)
* root volume: '''lv_root''' (only created when '''-m sys''' is specified or interactively selected)
* var volume: '''lv_var''' (only created when '''-m data''' is specified or interactively selected)

The '''lv_var''' or '''lv_root''' volumes are created to occupy all remaining space in the volume group.

If you need to change any of these settings, you can use <code>vgrename</code>, <code>lvrename</code>, <code>lvreduce</code> or <code>lvresize</code>.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.



 

== setup-lbu ==

This script will only be invoked for by <code>setup-alpine</code> when installing <code>data</code> installation types (ramdisk)

It configures where <code>lbu commit</code> will store the .apkovl backup. See [[Alpine local backup]] for more information.

When started, <code>setup-lbu</code> will prompt where to store your data. The options it will prompt for will be taken from the directories found in <code>/media</code> (except for <code>cdrom</code>). [not sure how these are mounted: are they automatically mounted by setup-lbu? Does the user have to manually mount using another tty?]

 

== setup-apkcache ==

This script will only be invoked for by <code>setup-alpine</code> when installing <code>data</code> installation types (ramdisk)

It configures where to save the apk package files. The apkcache is where apk stores downloaded packages, such that the system does not need to download them again on each reboot, and doesn't have to depend on the network. See [[Local APK cache]] for a detailed explanation.

You should be able to use a partition that you set up in the previous steps.

 

== setup-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

It allows to create boot media that boots the system running from RAM memory (diskless) like the installation images, but using a writable (i.e. not iso9660) filesystem. So that it can also serve to store local customizations (e.g. apkovl files and cached packages).

First, the script copies files from an ISO image (as file on a CD/DVD/USB etc.) onto a USB-Stick/CompactFlash/SDCard etc., or harddisk partition. And then, it installs the syslinux bootloader to make the device bootable.

However, its current syslinux installation seems to fail on non-FAT32 partitions. So in these cases, you may start over with a FAT32 filesystem, or rather with the desired filesystem and using <code>setup-bootable</code> only with the <code>-u</code> option, to skip the syslinux install, and then refer to the [[Create_a_Bootable_Device#Manually_copying_Alpine_files|manual method]] to fix the problem, or use one of the other bootloader options, instead.

{{Tip| The [[Bootloaders]] page shows different ways to setup booting, and multi-boot menus!}}

The setup-bootable script accepts the following arguments and command-line switches (you can run <code>setup-bootable -h</code> to see a usage message).

{{Cmd|setup-bootable <var>source</var> [<var>dest</var>]}}

The argument <var>source</var> can be a directory or an ISO (will be mounted to <code>MNT</code> or {{Path|/mnt}}) or a URL (will be downloaded with <code>WGET</code> or <code>wget</code>). The argument <var>dest</var> can be a directory mountpoint, or will default to {{Path|/media/usb}} if not supplied.

{{Define|-k|Keep alpine_dev in {{Path|syslinux.cfg}}; otherwise, replace with UUID.}}
{{Define|-u|Upgrade mode: keep existing {{Path|syslinux.cfg}} and don't run <code>syslinux</code>}}
{{Define|-f|Overwrite {{Path|syslinux.cfg}} even if '''-u''' was specified.}}
{{Define|-s|Force the running of <code>syslinux</code> even if '''-u''' was specified.}}
{{Define|-v|Verbose mode}}

The script will ensure that <var>source</var> and <var>dest</var> are available; will copy the contents of <var>source</var> to <var>dest</var>, ensuring first that there's enough space; and unless '''-u''' was specified, will make <var>dest</var> bootable.

Suppose the target device is /dev/sdXY, then this partition can be prepared for booting with
{{Cmd|# setup-bootable -v /media/<installation-media-device> /dev/sdXY
}}

For the manual way to set up boot media see [[Create_a_Bootable_Device#Manually_copying_Alpine_files|Manually_copying_Alpine_files]].

 

== setup-xorg-base ==

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

It configures a graphical environment, installing basic Xorg packages and udev (replacing mdev), and is also required for Wayland sessions.

The script installs, among other packages, e.g.: <code>xorg-server xf86-input-libinput xinit udev</code>.

Additional packages to install may be supplied as arguments.
{{cmd|setup-xorg-base [additional package(s) to install]}}

==== Video packages (optional) ====

You may install specific xf86 xorg driver packages for your video card's chipset, as they may support specific features, effects and acceleration modes, and avoid error messages during X initialization.

However, the most basic X features should work fine with just using the default kernel video-modesetting drivers.

Info about the particular video cards that are installed in the computer may be found in the list of PCI devices:
{{cmd|# apk add pciutils
$ lspci}}

To see available video driver packages run:
{{cmd|$ apk search xf86-video}}

For example,
* For an Sis video chipset install 'xf86-video-sis'.
{{Cmd|# apk add xf86-video-sis}}

Others:
* For Intel video chipsets install 'xf86-video-intel' and see [[Intel Video]].
{{Tip|In some cases, freezes on suspend/resume stop happening when changing the video port the monitor is connected to.}}
* For AMD Radeon Video see [[Radeon_Video]]
* For Alix1D use xf86-video-geode.
* In KVM/QEMU guests see [[QEMU#Using_Xorg_inside_Qemu|Xorg within KVM/QEMU]]
* In VirtualBox guests use xf86-video-vboxvideo, and install the [[VirtualBox_guest_additions|VirtualBox guest additions]] as well. They contain important parts for the driver.
* In VMware guests use xf86-video-vmware
* In Hyper-V guests use xf86-video-fbdev and install the [[Hyper-V_guest_services|Hyper-V guest services]] as well.

==== Input packages ====

If the Numlock settings are not working, or getting 'setleds not found' errors:

{{cmd|# apk add kbd}}

If some input device is not working at all, the available xf86-input drivers can be listed with:
{{cmd|$ apk search xf86-input}}

Typical legacy drivers:

{{cmd|# apk add xf86-input-mouse xf86-input-keyboard}}

And for touchpad tapping support on many laptops, also:

{{Cmd|# apk add xf86-input-synaptics}}

==== Configure xorg-server (optional) ====

On most systems, xorg should be able to autodetect all devices. However you can still configure xorg-server by hand by launching:
{{Cmd|# Xorg -configure}}
This will create a `/root/xorg.conf.new` file. You can modify this file to fit your needs. 
(When finished modifying and testing the above configuration file, move it to `/etc/X11/xorg.conf` for normal usage.)

==== Keyboard Layout (optional) ====

If you use a keyboard layout different than "us", and you are using a window manager or desktop environment that does not support to configure the keyboard layout itself, then you need to

* [[Enable_Community_Repository#Using_community_repositories|Enable the "community" repository]]

and install setxkbmap:

{{Cmd|# apk add setxkbmap}}

Then try
# setxkbmap <%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>

In order to make it persistent add this section to /etc/X11/xorg.conf:
{{Cmd|Section "InputClass"
Identifier "Keyboard Default"
MatchIsKeyboard "yes"
Option "XkbLayout" "<%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>"
EndSection
}}

Another way to change the keymap when logging into X is to use ~/.xinitrc. The following example loads a British keymap, simply add this line to the beginning of the file:
<code>setxkbmap gb &</code>

If you need to create the ~/.xinitrc file, you may also want to add a second line like <code>exec openbox-session</code> to still start the window manager with <code>startx</code> or <code>xinit</code>.

 

== Documentation needed ==

=== setup-xen-dom0 ===

 

=== setup-mta ===
Uses ssmtp.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

 

=== setup-acf ===
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

This script was named <code>setup-webconf</code> before Alpine 1.9 beta 4.

See [[:Category:ACF|ACF pages]] for more information.

= See also =
* [[Installation]]
* [[Post installation]]

[[Category:Installation]]

Raspberry Pi

2022-01-26T16:30:01Z

Jwatt: Update the link to the instructions on creating a bootable device and remove duplicated bullet points.

{{warning | 11 Feb 2021 - There is currently a known bug upstream [https://github.com/raspberrypi/firmware/issues/1529 kernel/initramfs cannot be loaded from subdirectory with same name as volume label] }}

{{TOC right}}

This tutorial will help you install Alpine Linux on your Raspberry Pi.

== Preparation ==

# [http://alpinelinux.org/downloads/ Download] the Alpine for Raspberry Pi tarball. You should be safe using the '''armhf''' build on all versions of Raspberry Pi (including Pi Zero and Compute Modules); but it may perform less optimally on recent versions of Raspberry Pi. The '''armv7''' build is compatible with Raspberry Pi 2 Model B. The '''aarch64''' build should be compatible with Raspberry Pi 2 Model v1.2, Raspberry Pi 3 and Compute Module 3, and Raspberry Pi 4 model B.
# [[Create_a_Bootable_Device#Manually_copying_Alpine_files|Create a bootable FAT32 partition on your SD card.]] The partitioning and formatting part of the instructions on the linked page could be done using a graphical partitioning tool such as [https://en.wikipedia.org/wiki/GNOME_Disks gnome-disks], just make sure the partition type is <code>W95 FAT32 (LBA)</code>. (The current type can be found in the "Type" column in the output of <code>fdisk -l</code>.)

Optionally create a '''usercfg.txt''' file on the partition to configure low-level system settings. Specifications can be found [https://www.raspberrypi.org/documentation/configuration/config-txt here]. However, note some settings can only be set directly in '''config.txt''', which may be overwritten after updates. In particular, <code>gpu_mem</code> will have no effect when specified in '''usercfg.txt''' ([https://github.com/raspberrypi/firmware/issues/1332 source]). Some interesting values include:
* To enable audio: <code>dtparam=audio=on</code>
* If you see black edges around your screen after booting the Pi, you can add <code>disable_overscan=1</code>

Recent versions include Broadcom firmware files. If you're using an older Alpine version, see [[#Wireless_support_with_older_Alpine_images|section below]].

== Installation ==

Alpine Linux will be installed in [[Installation#Installation_Handbook|diskless mode]], hence you need to use [[Alpine local backup|Alpine Local Backup (lbu)]] to save your modifications between reboots.

For users who will be using their Raspberry Pi in scenarios where there is not expected to be significant changes to disk after setup (like running a static HTTP server), this is likely preferable, as running the entire system from memory will improve performance (by avoiding the slow SD card) and improve the SD card life (by reducing the writes to the card, as all logging will happen in RAM). Diskless installations still allow you to install packages, save local files, and tune the system to your needs.

However, if you:
* Expect there will be constant changes to the disk after initial setup (for example, if you expect people to login and save files to their home directories)
* Need logs to persist after reboot
* Plan to install packages which consume more space than can be loaded into RAM
* Want to install kernel modules (such as ZFS or Wireguard)

Then you may be better served by a [[Classic install or sys mode on Raspberry Pi|sys-mode installation]].

Follow these steps to install Alpine Linux in Diskless Mode:

# Insert the SD card into the Raspberry Pi and power it on
# Login into the Alpine system as root. Leave the password empty.
# Type <code>setup-alpine</code>
# Once the installation is complete, commit the changes by typing <code>lbu commit -d</code>

Type <code>reboot</code> to verify that the installation was indeed successful.

== Post Installation ==

=== Update the System ===

After installation, make sure your system is up-to-date:

{{cmd|apk update
apk upgrade}}

Don't forget to save the changes:

{{cmd|lbu commit -d}}

Note: this does not upgrade the kernel. In order to upgrade the kernel, a full upgrade of the Alpine Linux version must be performed as described in [[Upgrading Alpine#Upgrading Alpine Linux on other removable media (such as CF/USB)|upgrading Alpine Linux for removable media]].

=== Clock-related error messages ===

During the booting time, you might notice errors related to the hardware clock. The Raspberry Pi does not have
a hardware clock, thus you need to disable the hwclock daemon and enable swclock:

{{cmd|rc-update add swclock boot # enable the software clock
rc-update del hwclock boot # disable the hardware clock}}

Since the Raspberry Pi does not have a clock, Alpine Linux needs to know what the time is by using a
[https://en.wikipedia.org/wiki/Network_Time_Protocol Network Time Protocol (NTP)] daemon. Make sure you have a
NTP daemon installed and running. If you are not sure, you can install an NTP client by running the following
command:

{{cmd|setup-ntp}}

The Busybox NTP client might be the most lightweight solution. Save the changes and reboot, once the NTP software is
installed and running:

{{cmd|lbu commit -d
reboot}}

After reboot, make sure the <code>date</code> command outputs the correct date and time.

=== WiFi on boot ===
If you have already [[Connecting_to_a_wireless_access_point|configured WiFi]] during the setup, the connection will not return on reboot.
You will need to start up a service to automatically connect to the wireless access point.
# Run <code>rc-update add wpa_supplicant boot</code> to connect to the wireless access point during bootup.
# Run it manually with <code>/etc/init.d/wpa_supplicant start</code>.

=== Enable OpenGL (Raspberry Pi 3/4) ===
Remount the boot partition writeable (i.e. <code>/media/mmcblk0p1</code>):

{{cmd|mount /media/mmcblk0p1 -o rw,remount}}

Add the following lines to <code>/media/mmcblk0p1/config.txt</code>:

gpu_mem=128
# Raspberry Pi 3:
dtoverlay=vc4-kms-v3d
# Raspberry Pi 4:
dtoverlay=vc4-fkms-v3d

256MB (and more on the Raspberry Pi 4) <code>gpu_mem</code> is also possible.

Install the Mesa drivers:

{{cmd|<nowiki># Raspberry Pi 3:
apk add mesa-dri-vc4
# Raspberry Pi 4:
apk add mesa-dri-gallium</nowiki>}}

Then reboot:

{{cmd|lbu_commit -d; reboot}}

=== WiFi drivers ===
As of Alpine 3.14, the WiFi drivers for the Raspberry Pi were moved from <code>linux-firmware-brcm</code> to the <code>linux-firmware-cypress</code> package (source?). Since the images seem to be an outdated version of the former, Wi-Fi will work during installation, but after the first update it will break.
Use the ethernet interface to download the required packages:

{{cmd|apk add linux-firmware-cypress}}

And reboot.

== Persistent storage ==
=== Loopback image with overlayfs ===

When you install Alpine in diskless mode, the entire system is loaded into memory at boot. If you want additional storage (for example, if you need more space than offered by your RAM) we need to create loop-back storage onto the SD card mounted with overlayfs.

First, make the SD card writable again and change fstab to always do so:
{{cmd|mount /media/mmcblk0p1 -o rw,remount
sed -i 's/vfat\ ro,/vfat\ rw,/' /etc/fstab}}

Create the loop-back file, this example is 1 GB:

{{cmd|dd if=/dev/zero of=/media/mmcblk0p1/persist.img bs=1024 count=0 seek=1048576}}

Install the ext utilities:

{{cmd|apk add e2fsprogs}}

Format the loop-back file:

{{cmd|mkfs.ext4 /media/mmcblk0p1/persist.img}}

Mount the storage:

{{cmd|echo "/media/mmcblk0p1/persist.img /media/persist ext4 rw,relatime,errors=remount-ro 0 0" >> /etc/fstab
mkdir /media/persist
mount -a}}

Make the overlay folders, we are using the /usr directory here, but you can use /home or anything else.
{{Warning|Overlay workdir needs to be an empty directory on the same filesystem mount as the upper directory. So each overlay must use its own workdir.}}

{{cmd|mkdir /media/persist/usr
mkdir /media/persist/.work_usr
echo "overlay /usr overlay lowerdir=/usr,upperdir=/media/persist/usr,workdir=/media/persist/.work_usr 0 0" >> /etc/fstab
mount -a}}

Your /etc/fstab should look something like this:
{{Cmd|/dev/cdrom /media/cdrom iso9660 noauto,ro 0 0
/dev/usbdisk /media/usb vfat noauto,ro 0 0
/dev/mmcblk0p1 /media/mmcblk0p1 vfat rw,relatime,fmask=0022,dmask=0022,errors=remount-ro 0 0
/media/mmcblk0p1/persist.img /media/persist ext4 rw,relatime,errors=remount-ro 0 0
overlay /usr overlay lowerdir=/usr,upperdir=/media/persist/usr,workdir=/media/persist/.work_usr 0 0}}

Now commit the changes: (optionally remove the e2fsprogs, but it does contain repair tools)
{{cmd|lbu_commit -d}}

Remember, with this setup if you install things and you have done this overlay for /usr, you must not commit the 'apk add', otherwise, while it boots it will try and install it to memory, not to the persistent storage.

If you do want to install something small at boot, you can use `apk add` and `lbu commit -d`.

If it is something a bit bigger, then you can use `apk add` but then not commit it. It will be persistent (in /user), but be sure to check everything you need is in that directory and not in folders you have not made persistent.

=== Traditional disk-based (sys) installation ===
{{Merge|Classic install or sys mode on Raspberry Pi|There's an existing page for sys-installations on RasPi.}}

It is also possible to switch to a fully disk-based installation. This is not yet formally supported, but can be done somewhat manually. This frees all the memory otherwise needed for the root filesystem, allowing more installed packages.

Split your SD card into two partitions: the FAT32 boot partition described above (in this example it'll be <code>mmcblk0p1</code>) , and a second partition to hold the root filesystem (here it'll be <code>mmcblk0p2</code>). Boot and configure your diskless system as above, then create a root filesystem:

{{cmd|apk add e2fsprogs
mkfs.ext4 /dev/mmcblk0p2}}

Now do a disk install via a mountpoint. The <code>setup-disk</code> script will give some errors about syslinux/extlinux, but you can ignore them.
The Raspberry Pi doesn't need them to boot.

{{cmd|<nowiki>mkdir /stage
mount /dev/mmcblk0p2 /stage
setup-disk -o /media/mmcblk0p1/MYHOSTNAME.apkovl.tar.gz /stage
# (ignore errors about syslinux/extlinux)</nowiki>}}

Add a line to <code>/stage/etc/fstab</code> to mount the Pi's boot partition again:

{{cmd|/dev/mmcblk0p1 /media/mmcblk0p1 vfat defaults 0 0}}

Now add a <code>root=/dev/mmcblk0p2</code> parameter to the Pi's boot command line, either <code>cmdline-rpi2.txt</code> or <code>cmdline-rpi.txt</code> depending on model:

{{cmd|<nowiki>mount -o remount,rw /media/mmcblk0p1
sed -i '$ s/$/ root=\/dev\/mmcblk0p2/' /media/mmcblk0p1/cmdline-rpi2.txt</nowiki>}}

You might also consider <code>overlaytmpfs=yes</code> here, which will cause the underlying SD card root filesystem to be mounted read-only, with an overlayed tmpfs for modifications which will be discarded at shutdown.

N.B. the contents of /boot will be ignored when the Pi boots. It will use the kernel, initramfs, and modloop images from the FAT32 boot partition. To update the kernel, initfs or modules, you will need to manually (generate and) copy these to the boot partition or you could use bind mount, in which case,
copying the files to boot partition manually, is not needed.

{{cmd|<nowiki>echo /media/mmcblk0p1/boot /boot none defaults,bind 0 0 >> /etc/fstab</nowiki>}}

=== Persistent Installation on Raspberry Pi 3 ===
See [[Classic install or sys mode on Raspberry Pi]] and https://web.archive.org/web/20171125115835/https://forum.alpinelinux.org/comment/1084#comment-1084

=== Persistent Installation on Raspberry Pi 4 ===
As of 3.14, setup-alpine should ask you if you want to create a sys mode partition on your Raspberry Pi 4.

== Troubleshooting ==

=== Long boot time when running headless ===

If no peripherals are connected, the system might hang for an exceptionally long period of time while it attempts to accumulate entropy.

If this is the case, simply plugging in any USB device should work around this issue.

'''Alternatively''', installing haveged, the random numbers generator, would speed up the process:

apk update
apk add haveged
rc-update add haveged boot
lbu commit -d
service haveged start

(Tested on a raspberry pi zero W in headless mode, no USB connected, Alpine 3.10.3)

=== apk indicating 'No space left on device' ===

Note some models of the Raspberry Pi such as the 3A+ only have 512M of RAM, which on fresh Alpine deployment will only leave around 200M for tmpfs root. It's important to keep this limitation in mind when using these boards.

=== Wireless support with older Alpine images ===

If you need Wi-Fi, you'll need to [https://github.com/RPi-Distro/firmware-nonfree/tree/master/brcm download] the latest Broadcom drivers to your SD card.
(Replace /mnt/sdcard with the correct mount point.)

git clone --depth 1 https://github.com/RPi-Distro/firmware-nonfree.git
cp firmware-nonfree/brcm/* /mnt/sdcard/firmware/brcm

== See Also ==

* [[Classic install or sys mode on Raspberry Pi]] - a variant.
* [[Raspberry Pi - Headless Installation]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Browser Client]]
* [[Linux Router with VPN on a Raspberry Pi]]
* [[Create a bootable SDHC from a Mac]]
* Build custom Raspberry Pi images based on Alpine via [https://github.com/tolstoyevsky/pieman Pieman]
* [[Tutorials and Howtos#Raspberry Pi]]

[[Category:Installation]]
[[Category: Raspberry]]

Create a Bootable Device

2022-01-26T16:22:46Z

Jwatt: Fill in lots of missing information from the manual method so it actually works (testing by installing alpine-rpi-3.15.0-aarch64.tar.gz to a Raspberry Pi 4)

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

If you can't/won't use '''setup-bootable''', you can manually create a customizable (writable) USB boot device instead.

=== Copy ISO content to USB stick as individual files ===

This method also works for Alpine tarballs (.tar.gz files) with a one line tweak (see below).

# Install some prerequisites. (If you're not currently using Alpine Linux then you probably have these installed already, otherwise you'll have to figure out how to install them.)
#: {{Cmd|apk add dosfstools apk add syslinux}}
# Set the environment variable 'mydev' to the [https://en.wikipedia.org/wiki/Device_file device file] name of the USB stick that Alpine Linux is to be installed to:
#: {{Warning | BE SURE TO GET THIS RIGHT OR ELSE YOU COULD OVERWRITE THE WRONG DISK! }}
#: {{Cmd|<nowiki>mydev=/dev/sdU</nowiki>}}
# Make sure that the target drive's existing partitions, if any, are not mounted:
#: {{Cmd|umount -q $mydev?}}
# Copy and paste the following as a single command to wipe the target drive, create an MBR partition table, and create a single FAT32 partition (you can ignore any "Partition #1 contains a vfat signature." warning message):
#: {{Cmd|<nowiki>fdisk -w always $mydev <<EOF
o
n
p
1
2048
-0
t
0c
a
w
EOF</nowiki>}}
# Format the new FAT32 partition with a FAT32 filesystem:
#: {{Cmd|<nowiki>mkdosfs -F32 ${mydev}1</nowiki>}}
# Copy the [https://wiki.syslinux.org/wiki/index.php?title=Mbr syslinix executable boot code] into the MBR table (if you're not currently using Alpine Linux you may need to adjust the path to syslinux's mbr.bin file):
#: {{Cmd|<nowiki>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=$mydev</nowiki>}}
# Install the syslinux bootloader files onto the FAT32 filesystem (ignore the "Hidden (2048) does not match sectors (62)" messages - modern systems use the partition table):
#: {{Cmd|syslinux ${mydev}1}}
# Copy the Alpine files to the FAT32 filesystem (if you're installing files from a .tar.gz archive, first extract the contents of the archive to an empty directory, then in the following replace "/media/cdrom" with the path to that directory):
#: {{Cmd|<nowiki>mydevname=$(basename $mydev)1
mkdir -p /media/$mydevname
mount -t vfat ${mydev}1 /media/$mydevname
# If copying from /media/cdrom, use:
( cd /media/cdrom && cp -a .alpine-release * /media/$mydevname )
# otherwise, if copying from an alpine .tar.gz file, use this instead:
#tar -p -s --atime-preserve --same-owner --one-top-level=/media/$mydevname -zxvf "$alpinetarball"
umount /media/$mydevname</nowiki>}}
# (''Optional'') Remove any apkovl files that were transfered as part of the copy process. This should be done if you wish to have a fresh install. Replace sdU with your device name)
#: {{Cmd|<nowiki>mount -t vfat ${mydev}1 /media/$mydevname
rm /media/$mydevname/*.apkovl.tar.gz
umount /media/$mydevname</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]

Create a Bootable Device

2022-01-25T23:17:11Z

Jwatt: Tweak intro prose to be clearer and add links.

This page is about creating directly customizable boot devices. If you are looking for instructions on creating (flashing) read-only (iso9660 "CD" filesystem) images onto installation media, see the [[Installation#Flashing_.28direct_data_writing.29_the_installation_image-file_onto_a_device_or_media|Installation]] page instead.

A directly customizable Alpine Linux boot medium is basically an Alpine system in '''[[Installation#Diskless_Mode|diskless]]''' or '''[[Installation#Data_Disk_Mode|data]]''' disk-mode installed to (and booting from) a device with a writable filesystem. It allows to also upgrade the kernel with its modules and firmware that is used to boot the system with the <code>[[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs|update-kernel]]</code> script.

The more general local customizations, the configs (.apkovl) and the package cache, may of course also be stored on the same device, as long as the hardware is not being set to be write-locked by a hardware switch.

= Requirements =

* An Alpine Linux CD-ROM or an .iso file containing the desired Alpine release ([https://alpinelinux.org/downloads/ Download]).
* A device like an USB drive (flash, external HD, card reader, etc.) or a CF "CompactFlash", or SDcard.

= Using setup-bootable =

This is now the preferable method to create a directly customizable bootable device.

It consists an [[Installation]] of a '''diskless''' or '''data''' mode system with configs and package cache on the target device, and using the <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code> script to make the device bootable.

= Manually copying Alpine files =

This process applies to Alpine Linux 1.9.0 or later.

It describes how to manually create a custom (writable) USB boot device.

=== Copy ISO content to USB stick as individual files ===

{{Warning | We assume here ''sdU'' is your USB stick which would hold bootable Alpine Linux files. }}

The following procedure is for the Alpine Linux distribution itself, if you are using other Linux distro or other operating system you should know the best how to install syslinux and where ''mbr.bin'' file is located on your filesystem.

# If you created a new partition above, format it with a FAT32 filesystem (replacing sdU with your device name):
#: {{Cmd|apk add dosfstools mkdosfs -F32 /dev/sdU1}}
# Install syslinux and MBR (replacing sdU with your device name):
#: {{Cmd|{{{|apk add syslinux dd if=/usr/share/syslinux/mbr.bin of=/dev/sdU}}} syslinux /dev/sdU1}}
#Copy the files to the boot device (replacing sdU with your device name):
#: {{Cmd|<nowiki>mkdir -p /media/sdU1
mount -t vfat /dev/sdU1 /media/sdU1
cd /media/cdrom
cp -a .alpine-release * /media/sdU1/
umount /media/sdU1</nowiki>}}
# (''Optional'') Remove any apkovl files that were transfered as part of the copy process. This should be done if you wish to have a fresh install. Replace sdU with your device name)
#: {{Cmd|<nowiki>mount -t vfat /dev/sdU1 /media/sdU1
rm /media/sdU1/*.apkovl.tar.gz
umount /media/sdU1</nowiki>}}

=== Troubleshooting ===

==== Wrong Device Name ====

If you cannot boot from the boot device and you see something like:
Mounting boot media failed.
initramfs emergency recovery shell launched. Type 'exit' to continue boot
then it is likely that the device name in {{Path|syslinux.cfg}} is wrong. You should replace the device name in this line:
append initrd=/boot/grsec.gz alpine_dev='''usbdisk''':vfat modules=loop,cramfs,sd-mod,usb-storage quiet
with the proper device name.
* For boot from USB, the device name should be 'usbdisk' (as shown above)
* For other options, you can run <code>cat /proc/partitions</code> to see the available disks (i.e. 'sda' or 'sdb')

==== Non-FAT32 Filesystems ====

===== Diskless and data mode booting =====

When the boot device is formatted with a filesystem other than those supported by default, the necessary initfs features need to be added to the modloop using <code>update-kernel</code>. See: [[Alpine_Linux_package_management#Upgrading_.22diskless.22_and_.22data.22_disk_mode_installs]]

===== Sys mode booting =====

Mount the boot device and edit the {{Path|syslinux.cfg}} file.

Then locate the "append" line, and change the <code>alpine_dev=</code> setting to match the used filesystem and add the filesystem's kernel module to the <code>modules=</code> list.

For example, change
append [...] alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
to
append [...] alpine_dev=usbdisk:'''ext4''' modules=loop,cramfs,sd-mod,usb-storage''',ext4''' quiet
in the case of an ext4 formatted partition. (Or correspondingly for other filesystems, if they are supported by syslinux and the Alpine Linux kernel.)

== Finishing installation ==

After one has booted the previously created Alpine Linux bootable USB medium, one has to prepare USB stick to hold local customizations and run ''setup-alpine'' to finish the installation.

First let's find out where is our just booted USB media mounted, the location could vary.

# mount | grep /media
/dev/sdU1 on /media/sdU1 type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)

Create local directory on USB media to hold local APK cache (see [[Alpine_Linux_package_management#Local_Cache|APK Local Cache]] for details).

# mount -o remount,rw /media/sdU1
# mkdir /media/sdU1/cache
# setup-apkcache /media/sdU1/cache
# ls -l /etc/apk/cache
lrwxrwxrwx 1 root root 17 Oct 19 13:16 /etc/apk/cache -> /media/sdU1/cache

Now run ''setup-alpine'' and proceed until a question about local disk selection - in ''diskless'' mode we won't use any disk (ie. our bootable media files is basically untouched) and we are going to use ''sdU1'' to hold our system customization.

# setup-alpine
...
Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdU1', 'usb' or 'none') [sdU1]:
Enter apk cache directory (or '?' or 'none') [/media/sdU1/cache]:

After the installer finished you can see how many created/modified files are detected and will be added to the backup:
# lbu status
# lbu status | wc -l
59
# lbu commit
# ls -l /media/sdU1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sdU1/foo.apkovl.tar.gz

Now all the customization are saved into the ''foo.apkovl.tar.gz'' compressed tarball on the USB stick itself.

= Troubleshooting =

=== Slow USB Devices ===
Specifying the 'waitusb=X' option at the end of the syslinux.cfg line might help with certain USB devices that take a bit longer to register. X stands for the amount of seconds kernel will wait before looking for the installation media.
append initrd=/boot/grsec.gz alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet '''waitusb=3'''

=== CF card readers ===

Some CF card readers have problems with the faster CF cards on the market. If you experience problems booting the CF card even after checking BIOS settings, you may need to use an older card.

Also, many CF card readers don't support DMA correctly, so you may need to add ''nodma'' to the ''append'' line of the syslinux.cfg file.

[[Category:Installation]]