Alpine Linux - User contributions [en]

Alpine configuration management scripts

2019-08-21T22:16:01Z

Aduty: /* setup-disk */

This page summarizes the low-level behavior of the {{Path|/sbin/setup-*}} scripts on the Alpine ISO (and in a normal Alpine install).

== setup-alpine ==

For a higher-level walkthrough (using the "sys" installmode), see [[Install to disk|Basic HDD install]].

This script accepts the following command-line switches (you can run <code>setup-alpine -h</code> to see a usage 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." See below for details.}}

The script's behavior is to do the following, in order. Bracketed options represent extra configuration choices that can be supplied when running the auxiliary setup scripts manually, or by supplying an "answerfile".

# <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: [[#setup-dns|setup-dns]] [-d example.com -n "8.8.8.8 [...]"]
# set the root password
# if not in quick mode, then: [[#setup-timezone|setup-timezone]] [-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>cron</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}}
# [[#setup-proxy|setup-proxy]] [-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: [[#setup-sshd|setup-sshd]] [-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> [[#setup-disk|setup-disk]] <code>-q</code> [-m data /dev/sda]
# 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]

== 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: {{Cmd|setup-dns -d example.org -n 8.8.8.8}}

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

search example.org
nameserver 8.8.8.8

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>http://10.0.0.1:8080</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-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-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-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 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 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 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, you can partition, format, and mount your volumes manually, 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-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Its purpose is to create media that boots into tmpfs by copying the contents of an ISO onto a USB key, CF, or similar media.

For a higher-level walkthrough, see [[Create a Bootable USB#Creating_a_bootable_Alpine_Linux_USB_Stick_from_the_command_line|Creating a bootable Alpine Linux USB Stick from the command line]].

This 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.



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

Installs the following packages: <code>xorg-server xf86-video-vesa xf86-input-evdev xf86-input-mouse xf86-input-keyboard udev</code>.

Additional packages can be supplied as arguments to <code>setup-xorg-base</code>. You might need, for example, some of: <code>xf86-input-synaptics xf86-video-<var>something</var> xinit</code>. For Qemu, see [[Qemu#Using_Xorg_inside_Qemu|Qemu]]. For Intel GPUs, see [[Intel Video]].

== Documentation needed ==

=== setup-xen-dom0 ===

=== setup-gparted-desktop ===
Uses openbox.

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

=== 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.

=== setup-ntp ===

[[Category:Installation]]

Managing ACF

2019-05-21T21:19:03Z

Aduty: /* User Management */

= Managing Your ACF Installation =

ACF is a powerful web application for configuring your Alpine Linux device. While all efforts are made to make ACF a secure application, it is, by its very nature, dangerous. The purpose of ACF is to give users the ability to administer the services running on the system. It is up to the system administrator to ensure that users do not receive more priviliges on ACF than they should have. Access control is provided by the following means:

*System Configuration
*User Management
*Roles Management
*Package-specific Management

== System Configuration ==

System administrators can do much to limit inappropriate access to ACF by properly managing the firewall and http services on the Alpine Linux device. Lock down access to ACF as much as possible. The following steps are highly recommended:

*Limit ACF to encrypted (HTTPS) access
*Do not make ACF available on Internet connections (if possible)
*Limit ACF access to specified IP or MAC addresses

{{tip|By default, ACF use '''mini_httpd''' and use port '''443'''. If you would like to change this port you simply have to specify the port in '''/etc/mini_httpd/mini_httpd.conf''' and restart: '''/etc/init.d/mini_httpd restart'''}}

== User Management ==

ACF includes user management under the '''System''' | '''User Management''' menu. Select the '''New User''' button to create a new user. Separate user accounts should be created for each ACF user. Each user account may belong to any number of ACF roles.

In Alpine Linux 1.8, the system includes two default users: ''alpine'' and ''foo''. The default password for both users is ''test123''. '''Replace the default users as soon as possible.''' In Alpine Linux 1.9 and later, you will be prompted to create an initial user the first time you try to log in. If you install ACF using the '''setup-acf''' script, you will be prompted for a password, and a ''root'' user will be created.

{{Warning|If you installed ACF before defining the root password, you must execute '''acfpasswd -s root'''}}

== Roles Management ==

ACF includes robust roles management under the '''System''' | '''Roles Management''' menu. Roles define the permissions that each user has in ACF. Specifically, they define which ACF actions a member of a role may invoke. The system provides built-in roles and the ability to create custom roles.

=== Built-in Roles ===

Each ACF package comes with built-in roles that define some typical usage scenarios. The five basic built-in roles are:

{| width="100%" border="1"
|-
| GUEST
| All users and guests (unauthenticated users) have access to basic status and login.
|-
| USER
| Typical end-users can view the status of services and restart them if necessary.
|-
| EDITOR
| Editors have the ability to change some settings using forms.
|-
| EXPERT
| Expert users can directly edit service configuration files.
|-
| ADMIN
| Administrators have access to all ACF actions.
|}

These built-in roles can be selected on a controller-by-controller basis (ie. /alpine-baselayout/alpine-baselayout/ADMIN) or globally (ie. ADMIN). The global built-in roles consist of all of the permissions of all of the corresponding controller-by-controller roles (ie. ADMIN contains /x/y/ADMIN for every x and y installed).

ACF packages may also include built-in roles that define specific usage scenarios for that package. For instance, acf-openssl is a fully functional certificate authority that separates the roles of submitting and approving certificate requests:

{| width="100%" border="1"
|-
| CERT_REQUESTER
| Users may submit requests for certificates and download those certificates when approved.
|-
| CERT_APPROVER
| Users may approve certificate requests.
|}

A system administrator may edit the built-in roles to add permissions, but may not delete the built-in roles or their default permissions. This feature may allow the system administrator to add some permission to one of the lower roles to meet his needs. This is the only way to modify the permissions of guests (unauthenticated users). More typically, a system administrator would assign each user to custom roles or to a combination of built-in and custom roles.

=== Custom Roles ===

Custom roles give the system administrator the ability to define roles that match the custom needs of his system. Custom roles may include as many or as few permissions as desired. So, a system administrator may fully define the permissions of each distinct user type in a separate role, or he may use combinations of more specific roles for each user.

Custom roles are created using the '''New Role''' button. The '''Create New Role''' and '''Edit Role''' forms list every ACF action currently installed on the system (depending on which ACF packages are installed). This list can be extensive if several ACF packages are installed. In general, each ACF package stands on its own, so permissions for one package do not depend on having permissions for any other packages. The built-in roles should be used as guides to show which permissions are typically grouped together.

== Package-specific Management ==

ACF packages may include their own package-specific management.

acf-tinydns manages a tinydns DNS server and includes permissions management on a domain by domain basis. This is available under the '''Networking''' | '''DNS''' | '''Permissions''' tab. The tinydns ACF package is designed to keep configuration for each domain in a separate file (see the '''List Domains''' tab). Permissions can then be set as to which domains may be viewed / edited by a specific user or members of a particular role.

= More Information =
For more information, please see [[Alpine Configuration Framework Design]].

[[Category:ACF]]
[[Category:Security]]

Managing ACF

2019-05-21T21:16:56Z

Aduty: /* System Configuration */

= Managing Your ACF Installation =

ACF is a powerful web application for configuring your Alpine Linux device. While all efforts are made to make ACF a secure application, it is, by its very nature, dangerous. The purpose of ACF is to give users the ability to administer the services running on the system. It is up to the system administrator to ensure that users do not receive more priviliges on ACF than they should have. Access control is provided by the following means:

*System Configuration
*User Management
*Roles Management
*Package-specific Management

== System Configuration ==

System administrators can do much to limit inappropriate access to ACF by properly managing the firewall and http services on the Alpine Linux device. Lock down access to ACF as much as possible. The following steps are highly recommended:

*Limit ACF to encrypted (HTTPS) access
*Do not make ACF available on Internet connections (if possible)
*Limit ACF access to specified IP or MAC addresses

{{tip|By default, ACF use '''mini_httpd''' and use port '''443'''. If you would like to change this port you simply have to specify the port in '''/etc/mini_httpd/mini_httpd.conf''' and restart: '''/etc/init.d/mini_httpd restart'''}}

== User Management ==

ACF includes user management under the '''System''' | '''User Management''' menu. Select the '''New User''' button to create a new user. Separate user accounts should be created for each ACF user. Each user account may belong to any number of ACF roles.

In Alpine Linux 1.8, the system includes two default users: ''alpine'' and ''foo''. The default password for both users is ''test123''. '''Replace the default users as soon as possible.''' In Alpine Linux 1.9 and later, you will be prompted to create an initial user the first time you try to log in. If you install ACF using the '''setup-acf''' script, you will be prompted for a password, and a ''root'' user will be created.

{{Warning|If you did install ACF before define the root password, you must execute '''acfpasswd -s root'''}}

== Roles Management ==

ACF includes robust roles management under the '''System''' | '''Roles Management''' menu. Roles define the permissions that each user has in ACF. Specifically, they define which ACF actions a member of a role may invoke. The system provides built-in roles and the ability to create custom roles.

=== Built-in Roles ===

Each ACF package comes with built-in roles that define some typical usage scenarios. The five basic built-in roles are:

{| width="100%" border="1"
|-
| GUEST
| All users and guests (unauthenticated users) have access to basic status and login.
|-
| USER
| Typical end-users can view the status of services and restart them if necessary.
|-
| EDITOR
| Editors have the ability to change some settings using forms.
|-
| EXPERT
| Expert users can directly edit service configuration files.
|-
| ADMIN
| Administrators have access to all ACF actions.
|}

These built-in roles can be selected on a controller-by-controller basis (ie. /alpine-baselayout/alpine-baselayout/ADMIN) or globally (ie. ADMIN). The global built-in roles consist of all of the permissions of all of the corresponding controller-by-controller roles (ie. ADMIN contains /x/y/ADMIN for every x and y installed).

ACF packages may also include built-in roles that define specific usage scenarios for that package. For instance, acf-openssl is a fully functional certificate authority that separates the roles of submitting and approving certificate requests:

{| width="100%" border="1"
|-
| CERT_REQUESTER
| Users may submit requests for certificates and download those certificates when approved.
|-
| CERT_APPROVER
| Users may approve certificate requests.
|}

A system administrator may edit the built-in roles to add permissions, but may not delete the built-in roles or their default permissions. This feature may allow the system administrator to add some permission to one of the lower roles to meet his needs. This is the only way to modify the permissions of guests (unauthenticated users). More typically, a system administrator would assign each user to custom roles or to a combination of built-in and custom roles.

=== Custom Roles ===

Custom roles give the system administrator the ability to define roles that match the custom needs of his system. Custom roles may include as many or as few permissions as desired. So, a system administrator may fully define the permissions of each distinct user type in a separate role, or he may use combinations of more specific roles for each user.

Custom roles are created using the '''New Role''' button. The '''Create New Role''' and '''Edit Role''' forms list every ACF action currently installed on the system (depending on which ACF packages are installed). This list can be extensive if several ACF packages are installed. In general, each ACF package stands on its own, so permissions for one package do not depend on having permissions for any other packages. The built-in roles should be used as guides to show which permissions are typically grouped together.

== Package-specific Management ==

ACF packages may include their own package-specific management.

acf-tinydns manages a tinydns DNS server and includes permissions management on a domain by domain basis. This is available under the '''Networking''' | '''DNS''' | '''Permissions''' tab. The tinydns ACF package is designed to keep configuration for each domain in a separate file (see the '''List Domains''' tab). Permissions can then be set as to which domains may be viewed / edited by a specific user or members of a particular role.

= More Information =
For more information, please see [[Alpine Configuration Framework Design]].

[[Category:ACF]]
[[Category:Security]]

Alpine Configuration Framework Design

2019-05-21T21:14:34Z

Aduty: /* Howto contribute */

= 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.)''<BR>

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.'''<BR>
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.<br>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'.<br>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!<br>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.<br>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).<br>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]]

Raspberry Pi

2019-05-07T20:06:20Z

Aduty: /* Preparation */

[[Category:Installation]]
This tutorial will help you install Alpine Linux on your Raspberry Pi.

== Preparation ==

This section will help you format and partition your SD card:

# [http://alpinelinux.org/downloads/ Download] Alpine for Raspberry Pi tarball which is named as <code>alpine-rpi-<version>-armhf.tar.gz</code>. You will need version 3.2.0 or greater if you have a Raspberry Pi 2.
# Mount your SD card to your workstation
# Use [https://en.wikipedia.org/wiki/GNOME_Disks gnome-disks] or [http://linux.die.net/man/8/fdisk fdisk] to create a FAT32 partition. If you are using fdisk, the FAT32 partition type is called ''W95 FAT32 (LBA)'' and its ID is 0x0C.
# Mark the newly created partition as bootable and save
# Mount the previously created partition
# Extract the tarball contents to your FAT32 partition
# Unmount the SD Card.

== Installation ==

Optionally create a "usercfg.txt" file on your SD card to configure low-level system settings. Specifications can be found [https://www.raspberrypi.org/documentation/configuration/config-txt here]. Some interesting values include:
* Enable audio: dtparam=audio=on
* If you see black edges around your screen: disable_overscan=1

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

# Insert the SD Card into the Raspberry Pi and turn 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 ===

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

{{cmd|apk update
apk upgrade}}

Don't forget to save the changes:

{{cmd|lbu commit -d}}

=== 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 and therefore 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 Raspberry Pi does not have a clock, the 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 that you a
NTP daemon installed and running. If you are not sure, then you can install NTP client by running the following
command:

{{cmd|setup-ntp}}

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 that the <code>date</code> command outputs the correct date and time.

=== X11 Setup ===
Here are what you need if you want to try and run a single X11 application like a browser kiosk or maybe even a desktop: {{cmd|setup-xorg-base
apk add xf86-video-fbdev xf86-video-vesa xf86-input-mouse xf86-input-keyboard dbus setxkbmap kbd
rc-update add dbus}}

Install XFCE:
{{cmd|apk add xfce4}}

Commit your changes:
{{cmd|lbu_commit -d}}

{{cmd|startx}}

=== Enable OpenGL (RPi 3) ===

Remount the boot partition writeable (ie. /media/mmcblk0p1):

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

Add the following lines to /media/mmcblk0p1/config.txt

dtoverlay=vc4-kms-v3d
gpu_mem=128

256MB gpu_mem is also possible

Install mesa-dri-vc4:
{{cmd|apk add mesa-dri-vc4}}

Reboot:

{{cmd|lbu_commit -d; reboot}}

== Persistent storage ==

=== Loopback image with overlayfs ===

The install is in disk-less mode and forces everything into memory, if you want additional storage we need to create loop-back storage onto the SD 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 doing /usr here, but you can do /home or anything else:

{{cmd|mkdir /media/persist/usr
mkdir /media/persist/.work
echo "overlay /usr overlay lowerdir=/usr,upperdir=/media/persist/usr,workdir=/media/persist/.work 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 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 and not to the persist 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 do check everything you need is in that directory and not in folders you have not made persistent.

=== Traditional disk-based (sys) installation ===

{{Warning|This isn't yet supported by the Alpine setup scripts for Raspberry Pi. It requires manual intervention, and might break.}}

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 these: the Raspberry Pi doesn't need this to boot anyway.

{{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 on shutdown.

Beware, though, that <b>the contents of /boot will be ignored when the Pi boots</b>: 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 so that manually copy the files to boot partition is not needed.

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

=== Persistent Installation on RPi3 ===

See this page : https://wiki.alpinelinux.org/wiki/Classic_install_or_sys_mode_on_Raspberry_Pi

See https://web.archive.org/web/20171125115835/https://forum.alpinelinux.org/comment/1084#comment-1084

== See Also ==

* [[Classic install or sys mode on Raspberry Pi]] - a variant.
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[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]

Installing on GPT LVM

2019-03-26T21:48:30Z

Aduty:

This is an updated version of this Howto: [http://wiki.alpinelinux.org/wiki/Setting_up_LVM_on_GPT-labeled_disks Setting up LVM on GPT-labeled disks].

This document describes how to set up a system booting from a logical volume in Alpine Linux using lvm2 and GPT-labeled disks.

Begin by booting from Alpine Linux installation media in the usual way. Log in as `root`, run `setup-alpine`, and answer `none` when asked to choose a disk.

=== Info ===
Alpine Linux ISO used in this installation: alpine-vanilla-3.7.0-x86_64.iso

This PC has BIOS, not UEFI (UEFI installation may differ)

Tested on APU4C with 30GB Kingston mSata SSD (SMS200S3/30G).

=== Partitioning ===
We need to install some tools, as 'gptfdisk' and 'sgdisk' are part of main.

Install gptfdisk.
{{Cmd|apk add -U gptfdisk sgdisk}}

Create some partitions. In my case the SSD disk is found as sda, so I will use 'sda' throughout the process.
{{Cmd|gdisk /dev/sda}}
# create a new empty GUID partition table (GPT) with 'o'
o # then 'y' to confirm
# create some partitions: BIOS (needed only for GRUB2), Boot (needed by SYSLINUX), and LVM
n
1
<enter>
+2M
ef02
n
2
<enter>
+100M
8300
n
3
<enter>
<enter>
8e00
# print the partition table with 'p'

You should get something like this:
Number Start (sector) End (sector) Size Code Name
1 2048 6143 2.0 MiB EF02 BIOS boot partition
2 6144 210943 100.0 MiB 8300 Linux filesystem
3 210944 15662270 7.4 GiB 8E00 Linux LVM

We need to set the 'legacy BIOS bootable' flag on our boot partition, which can be done in gdisk by first entering expert mode with 'x' then editing attributes with 'a'. It's used by SYSLINUX's GPT support to identify a partition that holds second-stage boot code.
x
a
2
2

It looks like this:
Command (? for help): x

Expert command (? for help): a
Partition number (1-3): 2
Known attributes are:
0: system partition
1: hide from EFI
2: legacy BIOS bootable
60: read-only
62: hidden
63: do not automount

Attribute value is 0000000000000000. Set fields are:
No fields set

Toggle which attribute field (0-63, 64 or <Enter> to exit): 2
Have enabled the 'legacy BIOS bootable' attribute.
Attribute value is 0000000000000004. Set fields are:
2 (legacy BIOS bootable)

Press 'Enter' to exit the expert mode and then write table to disk and exit gdisk with 'w'.

You can verify the legacy_boot flag with sgdisk (also part of the gptfdisk).

{{Cmd|1=sgdisk /dev/sda --attributes=1:show}}
{{Cmd|1=sgdisk /dev/sda --attributes=2:show}}
2:2:1 (legacy BIOS bootable)
{{Cmd|1=sgdisk /dev/sda --attributes=3:show}}

Remove gptfdisk (if not needed anymore).
{{Cmd|apk del gptfdisk sgdisk}}

=== LVM Setup ===
Now we can setup LVM on the third partition created in the process above.
{{Cmd|apk add lvm2 e2fsprogs syslinux}}

{{Cmd|pvcreate /dev/sda3}}
Physical volume "/dev/sda3" successfully created
{{Cmd|vgcreate vg00 /dev/sda3}}
Volume group "vg00" successfully created
{{Cmd|lvcreate -n alpine_rootfs -L4G vg00}}
Logical volume "alpine_rootfs" created
{{Cmd|lvcreate -n swap -C y -L 512M vg00}}
Logical volume "swap" created
{{Cmd|rc-update add lvm}}
* service lvm added to runlevel default
{{Cmd|vgchange -ay}}
2 logical volume(s) in volume group "vg00" now active

Format new logical volume and activate swap.
{{Cmd|mkfs.ext3 /dev/sda2}}
{{Cmd|mkfs.ext4 /dev/vg00/alpine_rootfs}}
{{Cmd|mkswap /dev/vg0/swap}}

Mount for finishing Alpine Linux installation.
{{Cmd|mount -t ext4 /dev/vg00/alpine_rootfs /mnt}}
{{Cmd|mkdir /mnt/boot}}
{{Cmd|mount -t ext3 /dev/sda2 /mnt/boot}}

=== Finish installation ===
Run this command to finish installing Alpine Linux to our newly mounted partition on /mnt:
{{Cmd|setup-disk -m sys /mnt}}

Output of setup-disk should be like this:
Installing system on /dev/vg00/alpine_rootfs:
/mnt/boot is device /dev/sda2
/boot is device /dev/sda2
You might need fix the MBR to be able to boot

=== Syslinux ===
Install the MBR.
{{Cmd|1=dd bs=440 conv=notrunc count=1 if=/usr/share/syslinux/gptmbr.bin of=/dev/sda}}

Reboot and enjoy your new Alpine Linux installation!

[[Category:Installation]]

Creating an Alpine package

2019-03-06T06:05:10Z

Aduty: /* install */

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Include:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on Freenode's #alpine-devel on IRC.

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Include:Newapkbuild}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory.<BR>
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== source ====

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[Creating an Alpine package#install|install variable]]), patches, and all other necessary files.

Here are few things to note:

* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: {{cmd|abuild checksum}}
: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

* abuild currently supports the following protocols for remote file retrieval:
** http
** https
** ftp



* abuild currently supports the following archive types/archive file extensions:
** .tar
** .tar.gz / .tgz
** .tar.bz2
** .tar.lz (only in Alpine >=3.7)
** .tar.lzma
** .tar.xz
** .zip

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [http://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [http://www.archlinux.org/packages/search/ Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the <code>$depends</code> variable. We do this by using <code>scanelf</code>. If scanelf is not yet installed on your system you can do that by installing {{Pkg|pax-utils}}.

{{Cmd|scanelf -nR pkg}}

An example output of {{Pkg|libcurl}} would be:

ET_DYN libssl.so.0.9.8,libcrypto.so.0.9.8,libz.so.1,libc.so.0,ld-uClibc.so.0 pkg/usr/lib/libcurl.so.4.1.1

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved] we need to provide it with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This can be one of: ''x86, x86_64, all,'' or ''noarch'', where ''all'' means all architectures, and ''noarch'' means it's architecture-independent (ie, a pure-python package).
{{Tip|To determine if your APKBUILD can use ''noarch'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so that if you change something in your APKBUILD file without changing the actual $pkgver, you can increment pkgrel so apk tools will detect it as an update. For instance, if you forget to add a dependency, you can add it afterward and you can +1 pkgver so apk finds this update and adds the missing dependency. When there's an upstream version change, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after the package is installed. Can be used to generate font cache and similar.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package has a pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

<br> To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -urp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [http://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

make

To disable parallel we use:

make -j1

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

make DESTDIR="$pkgdir" install

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

builddir="$srcdir"/$pkgname-$pkgver

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependency's from your repository and builds it, afterwards it will uninstall all those depending packages again. You could also use the '''-R''' switch which would build your package including the dependency packages.

{{Cmd|abuild -r}}

== Testing the package locally ==

When it completes, your package will be found in a subfolder of ''~/packages''. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

To install the package, you could:
{{Cmd|sudo apk add /home/<USER>/packages/testing/x86_64/$pkgname-$pkgver.apk}}

Or, modify your /etc/apk/repositories so that it points to your local ARCH/APKINDEX.tar.gz. Change USER to your login name.

{{Cat|/etc/apk/repositories|
/home/USER/packages/testing/
/home/USER/packages/community/
/home/USER/packages/main/
/media/sdc/apks
#http://dl-2.alpinelinux.org/alpine/v3.7/main
#http://dl-2.alpinelinux.org/alpine/v3.7/community
http://dl-2.alpinelinux.org/alpine/edge/main
http://dl-2.alpinelinux.org/alpine/edge/community
http://dl-2.alpinelinux.org/alpine/edge/testing
}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our github repo, you can create PR's for each package. Please squash all commits into a single one per PR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a pull request to [https://github.com/alpinelinux/aports/ Alpine's mirror on GitHub] (read instructions [https://github.com/alpinelinux/aports/blob/master/.github/CONTRIBUTING.md here]).

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[http://lists.alpinelinux.org/alpine-aports/ alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Travis CI and automated testing ==

Travis CI, as in continuous integration automated testing, isn't always required, but 99% of the time it is strongly encouraged to pass with a green checkmark. Passing Travis CI ensures that your package works on another machine and builds the image starting from nothing. One reason why your package fails to build on the remote server is that you may inadvertently add a package dependency as in creating multiple packages at the same time or forgot to remove a dependency and forgot to mark it as a makedepends.

When you submit your APKBUILD as a pull request, the Travis CI server will construct the build environment from [https://github.com/alpinelinux/aports/blob/master/.travis/install-alpine#L28 main] [https://github.com/alpinelinux/aports/blob/master/.travis/common.sh#L5 Edge] apks.

The environment is just like a boot into command line so it is minimal. Don't assume that you boot into X.

The server/configuration cannot do testing/check() testing on hardware accelerated OpenGL apps.

== Send a patch ==

[[Creating_patches#Only_the_last_commit_with_.27git_send-email.27|git send-email]] will do that for you.

== GitHub Tagging ==

If you see your pull requested labeled on GitHub this is what they mean:

*A-add - The pull requester wanted to add this brand new package.
*A-upgrade - The pull requester wanted to update the package.
*A-improve - The pull requester wanted to improve an existing package.
*A-fix - The pull requester wanted to fix a bug with the existing package.
*S-changes-requested - An admin wants you to add or remove a subpackage or fix something as in messy code.
*S-needs-review - An admin needs someone to do a code review on your package.
*S-broken - The package fails to build locally on the code reviewer machine.
*ci-malfunction - Travis CI doesn't work with this package as in exceeded time.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[Category:Development]]

Creating an Alpine package

2019-03-06T06:01:31Z

Aduty: /* pkgrel */

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Include:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on Freenode's #alpine-devel on IRC.

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Include:Newapkbuild}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory.<BR>
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== source ====

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[Creating an Alpine package#install|install variable]]), patches, and all other necessary files.

Here are few things to note:

* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: {{cmd|abuild checksum}}
: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

* abuild currently supports the following protocols for remote file retrieval:
** http
** https
** ftp



* abuild currently supports the following archive types/archive file extensions:
** .tar
** .tar.gz / .tgz
** .tar.bz2
** .tar.lz (only in Alpine >=3.7)
** .tar.lzma
** .tar.xz
** .zip

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [http://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [http://www.archlinux.org/packages/search/ Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the <code>$depends</code> variable. We do this by using <code>scanelf</code>. If scanelf is not yet installed on your system you can do that by installing {{Pkg|pax-utils}}.

{{Cmd|scanelf -nR pkg}}

An example output of {{Pkg|libcurl}} would be:

ET_DYN libssl.so.0.9.8,libcrypto.so.0.9.8,libz.so.1,libc.so.0,ld-uClibc.so.0 pkg/usr/lib/libcurl.so.4.1.1

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved] we need to provide it with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This can be one of: ''x86, x86_64, all,'' or ''noarch'', where ''all'' means all architectures, and ''noarch'' means it's architecture-independent (ie, a pure-python package).
{{Tip|To determine if your APKBUILD can use ''noarch'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so that if you change something in your APKBUILD file without changing the actual $pkgver, you can increment pkgrel so apk tools will detect it as an update. For instance, if you forget to add a dependency, you can add it afterward and you can +1 pkgver so apk finds this update and adds the missing dependency. When there's an upstream version change, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after package is installed. Can be used to generate font cache and similar.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

<br> To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -urp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [http://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

make

To disable parallel we use:

make -j1

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

make DESTDIR="$pkgdir" install

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

builddir="$srcdir"/$pkgname-$pkgver

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependency's from your repository and builds it, afterwards it will uninstall all those depending packages again. You could also use the '''-R''' switch which would build your package including the dependency packages.

{{Cmd|abuild -r}}

== Testing the package locally ==

When it completes, your package will be found in a subfolder of ''~/packages''. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

To install the package, you could:
{{Cmd|sudo apk add /home/<USER>/packages/testing/x86_64/$pkgname-$pkgver.apk}}

Or, modify your /etc/apk/repositories so that it points to your local ARCH/APKINDEX.tar.gz. Change USER to your login name.

{{Cat|/etc/apk/repositories|
/home/USER/packages/testing/
/home/USER/packages/community/
/home/USER/packages/main/
/media/sdc/apks
#http://dl-2.alpinelinux.org/alpine/v3.7/main
#http://dl-2.alpinelinux.org/alpine/v3.7/community
http://dl-2.alpinelinux.org/alpine/edge/main
http://dl-2.alpinelinux.org/alpine/edge/community
http://dl-2.alpinelinux.org/alpine/edge/testing
}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our github repo, you can create PR's for each package. Please squash all commits into a single one per PR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a pull request to [https://github.com/alpinelinux/aports/ Alpine's mirror on GitHub] (read instructions [https://github.com/alpinelinux/aports/blob/master/.github/CONTRIBUTING.md here]).

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[http://lists.alpinelinux.org/alpine-aports/ alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Travis CI and automated testing ==

Travis CI, as in continuous integration automated testing, isn't always required, but 99% of the time it is strongly encouraged to pass with a green checkmark. Passing Travis CI ensures that your package works on another machine and builds the image starting from nothing. One reason why your package fails to build on the remote server is that you may inadvertently add a package dependency as in creating multiple packages at the same time or forgot to remove a dependency and forgot to mark it as a makedepends.

When you submit your APKBUILD as a pull request, the Travis CI server will construct the build environment from [https://github.com/alpinelinux/aports/blob/master/.travis/install-alpine#L28 main] [https://github.com/alpinelinux/aports/blob/master/.travis/common.sh#L5 Edge] apks.

The environment is just like a boot into command line so it is minimal. Don't assume that you boot into X.

The server/configuration cannot do testing/check() testing on hardware accelerated OpenGL apps.

== Send a patch ==

[[Creating_patches#Only_the_last_commit_with_.27git_send-email.27|git send-email]] will do that for you.

== GitHub Tagging ==

If you see your pull requested labeled on GitHub this is what they mean:

*A-add - The pull requester wanted to add this brand new package.
*A-upgrade - The pull requester wanted to update the package.
*A-improve - The pull requester wanted to improve an existing package.
*A-fix - The pull requester wanted to fix a bug with the existing package.
*S-changes-requested - An admin wants you to add or remove a subpackage or fix something as in messy code.
*S-needs-review - An admin needs someone to do a code review on your package.
*S-broken - The package fails to build locally on the code reviewer machine.
*ci-malfunction - Travis CI doesn't work with this package as in exceeded time.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[Category:Development]]

Creating an Alpine package

2019-03-06T05:51:43Z

Aduty: /* depends & makedepends */

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Include:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on Freenode's #alpine-devel on IRC.

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Include:Newapkbuild}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory.<BR>
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== source ====

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[Creating an Alpine package#install|install variable]]), patches, and all other necessary files.

Here are few things to note:

* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: {{cmd|abuild checksum}}
: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

* abuild currently supports the following protocols for remote file retrieval:
** http
** https
** ftp



* abuild currently supports the following archive types/archive file extensions:
** .tar
** .tar.gz / .tgz
** .tar.bz2
** .tar.lz (only in Alpine >=3.7)
** .tar.lzma
** .tar.xz
** .zip

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [http://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [http://www.archlinux.org/packages/search/ Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the <code>$depends</code> variable. We do this by using <code>scanelf</code>. If scanelf is not yet installed on your system you can do that by installing {{Pkg|pax-utils}}.

{{Cmd|scanelf -nR pkg}}

An example output of {{Pkg|libcurl}} would be:

ET_DYN libssl.so.0.9.8,libcrypto.so.0.9.8,libz.so.1,libc.so.0,ld-uClibc.so.0 pkg/usr/lib/libcurl.so.4.1.1

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved] we need to provide it with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This can be one of: ''x86, x86_64, all,'' or ''noarch'', where ''all'' means all architectures, and ''noarch'' means it's architecture-independent (ie, a pure-python package).
{{Tip|To determine if your APKBUILD can use ''noarch'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so if you change something to your APKBUILD file without changing the actual $pkgver you can increment pkgrel so apk tools will detect it as an update. For instance if you forget to add a dependency you can add it afterward and you can +1 pkgver so apk finds this update and add the missing dependency. When there's an upstream version changes, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after package is installed. Can be used to generate font cache and similar.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

<br> To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -urp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [http://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

make

To disable parallel we use:

make -j1

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

make DESTDIR="$pkgdir" install

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

builddir="$srcdir"/$pkgname-$pkgver

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependency's from your repository and builds it, afterwards it will uninstall all those depending packages again. You could also use the '''-R''' switch which would build your package including the dependency packages.

{{Cmd|abuild -r}}

== Testing the package locally ==

When it completes, your package will be found in a subfolder of ''~/packages''. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

To install the package, you could:
{{Cmd|sudo apk add /home/<USER>/packages/testing/x86_64/$pkgname-$pkgver.apk}}

Or, modify your /etc/apk/repositories so that it points to your local ARCH/APKINDEX.tar.gz. Change USER to your login name.

{{Cat|/etc/apk/repositories|
/home/USER/packages/testing/
/home/USER/packages/community/
/home/USER/packages/main/
/media/sdc/apks
#http://dl-2.alpinelinux.org/alpine/v3.7/main
#http://dl-2.alpinelinux.org/alpine/v3.7/community
http://dl-2.alpinelinux.org/alpine/edge/main
http://dl-2.alpinelinux.org/alpine/edge/community
http://dl-2.alpinelinux.org/alpine/edge/testing
}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our github repo, you can create PR's for each package. Please squash all commits into a single one per PR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a pull request to [https://github.com/alpinelinux/aports/ Alpine's mirror on GitHub] (read instructions [https://github.com/alpinelinux/aports/blob/master/.github/CONTRIBUTING.md here]).

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[http://lists.alpinelinux.org/alpine-aports/ alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Travis CI and automated testing ==

Travis CI, as in continuous integration automated testing, isn't always required, but 99% of the time it is strongly encouraged to pass with a green checkmark. Passing Travis CI ensures that your package works on another machine and builds the image starting from nothing. One reason why your package fails to build on the remote server is that you may inadvertently add a package dependency as in creating multiple packages at the same time or forgot to remove a dependency and forgot to mark it as a makedepends.

When you submit your APKBUILD as a pull request, the Travis CI server will construct the build environment from [https://github.com/alpinelinux/aports/blob/master/.travis/install-alpine#L28 main] [https://github.com/alpinelinux/aports/blob/master/.travis/common.sh#L5 Edge] apks.

The environment is just like a boot into command line so it is minimal. Don't assume that you boot into X.

The server/configuration cannot do testing/check() testing on hardware accelerated OpenGL apps.

== Send a patch ==

[[Creating_patches#Only_the_last_commit_with_.27git_send-email.27|git send-email]] will do that for you.

== GitHub Tagging ==

If you see your pull requested labeled on GitHub this is what they mean:

*A-add - The pull requester wanted to add this brand new package.
*A-upgrade - The pull requester wanted to update the package.
*A-improve - The pull requester wanted to improve an existing package.
*A-fix - The pull requester wanted to fix a bug with the existing package.
*S-changes-requested - An admin wants you to add or remove a subpackage or fix something as in messy code.
*S-needs-review - An admin needs someone to do a code review on your package.
*S-broken - The package fails to build locally on the code reviewer machine.
*ci-malfunction - Travis CI doesn't work with this package as in exceeded time.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[Category:Development]]

Package policies

2019-03-02T19:53:18Z

Aduty: /* Package Names */

The Alpine Linux Package Policies describe some of the policies when creating packages.

== Package Names ==
* All package names should be lowercase.
* Development files are placed in subpackages with ''-dev'' suffix (e.g. uclibc-dev)
* Documentation files (incl. man pages) are placed in subpackages with ''-doc'' suffix (e.g. expat-doc)
* Lua modules (not applications) are prefixed with ''lua-''. (e.g. lua-posix)
* Perl modules (not applications) are prefixed with ''perl-''. (e.g. perl-xml-parser)
* Python 2 modules (not applications) are prefixed with ''py2-''. (e.g. py2-libxml2)
* [[TODO:py3 packages|Python 3]] modules (not applications) are prefixed with ''py3-''. (e.g. py3-libxml2)
* Kernels and third party modules should be suffixed with the kernel flavor. (e.g., ''-grsec'', ''-vserver'').
# Don't use ''-'' sign in kernel flavor name.
# Specify ''KERNEL_FLAVOR_DEFAULT'' as your kernel flavor if you want boot your kernel by default.

== Package versions ==
* Package versions are similar to gentoo.

== Licensing ==
* The license of the program should be based on the licenses approved by the [http://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses Free Software Foundation] or [http://www.opensource.org/licenses/ OSI].
* If you are unsure about the license, please ask in our [[IRC]] channel.

[[Category:Development]]

Nextcloud

2019-03-01T00:58:05Z

Aduty: /* Installation */

[http://nextcloud.com/ Nextcloud] is WedDAV-based solution for storing and sharing on-line your data, files, images, video, music, calendars and contacts. [http://karlitschek.de/2016/06/nextcloud/ Nextcloud is a fork of ownCloud with enterprise features included].

= Installation =
{{pkg|nextcloud}} is available from Alpine 3.5 and greater.

Before you start installing anything, make sure you have the latest packages available. Make sure you are using an 'http' repository in your {{path|/etc/apk/repositories}} file, then:
{{cmd|apk update}}
{{tip|Detailed information is found in [[Include:Upgrading_to_latest_release|this]] doc.}}

== Database ==
First you have to decide which database to use. Use one of the databases listed below.

=== Sqlite ===
All you need to do is to install the package:
{{cmd|apk add nextcloud-sqlite}}

=== PostgreSQL ===
Install the package:
{{cmd|apk add nextcloud-pgsql}}

Next thing is to configure and start the database:
{{cmd|/etc/init.d/postgresql setup
/etc/init.d/postgresql start}}

Next, you need to create a user and temporarily grant the CREATEDB privilege:
{{cmd|psql -U postgres
CREATE USER mycloud WITH PASSWORD 'test123';
ALTER ROLE mycloud CREATEDB;
\q}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

=== MariaDB ===
Install the package:
{{cmd|apk add nextcloud-mysql mariadb mariadb-client}}

Now configure and start {{pkg|mariadb}}:
{{cmd|/etc/init.d/mariadb setup
/etc/init.d/mariadb start
/usr/bin/mysql_secure_installation}}
Follow the wizard to setup passwords, etc.
{{Note|Remember the usernames/passwords that you set using the wizard. You will need them later.}}

Next, you need to create a user and database and set permissions:
{{cmd|mysql -u root -p
CREATE DATABASE nextcloud;
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost' IDENTIFIED BY 'test123';
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost.localdomain' IDENTIFIED BY 'test123';
FLUSH PRIVILEGES;
EXIT}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

{{pkg|mariadb-client}} is not needed anymore. Let's uninstall it:
{{cmd|apk del mariadb-client}}

== Webserver ==
Next thing is to choose, install, and configure a webserver. In this example we will install {{pkg|nginx}} or {{pkg|lighttpd}}. ''Nginx'' is preferred over ''Lighttpd'' since the latter will consume a lot of memory when working with large files (see [http://redmine.lighttpd.net/issues/1283 lighty bug #1283]). You are free to install any other webserver of your choice as long as it supports PHP and FastCGI. Generating an SSL certificate for your webserver is outside of the scope of this document.

=== Nginx ===
Install the needed packages:
{{cmd|apk add nginx php7-fpm}}

'''Remove/comment''' any section like this in {{path|/etc/nginx/nginx.conf}}:
{{cat|/etc/nginx/nginx.conf|
server {
listen ...
}
}}

Include the following directive in {{path|/etc/nginx/nginx.conf}}:
{{cat|/etc/nginx/nginx.conf|
http {
...
include /etc/nginx/sites-enabled/*;
...
}}

Create directories for your websites:
{{cmd|mkdir /etc/nginx/sites-available}}
{{cmd|mkdir /etc/nginx/sites-enabled}}

Create a configuration file for your site in {{path|/etc/nginx/sites-available/mysite.mydomain.com}}:
<pre>
server {
#listen [::]:80; #uncomment for IPv6 support
listen 80;
return 301 https://$host$request_uri;
server_name mysite.mydomain.com;
}

server {
#listen [::]:443 ssl; #uncomment for IPv6 support
listen 443 ssl;
server_name mysite.mydomain.com;

root /usr/share/webapps/nextcloud;
index index.php index.html index.htm;
disable_symlinks off;

ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;

ssl_session_cache shared:SSL:1m;
ssl_session_timeout 5m;

#Enable Perfect Forward Secrecy and ciphers without known vulnerabilities
#Beware! It breaks compatibility with older OS and browsers (e.g. Windows XP, Android 2.x, etc.)
#ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA;
#ssl_prefer_server_ciphers on;

location / {
try_files $uri $uri/ /index.html;
}

# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if (!-f $document_root$fastcgi_script_name) {
return 404;
}
fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/run/php-fpm/socket;
fastcgi_index index.php;
include fastcgi.conf;
}
}
</pre>

If you are running from RAM and you're dealing with large files you might need to move the FastCGI temp file from {{path|/tmp}} to {{path|/var/tmp}} or to a directory that is mounted on hdd:
<pre>
fastcgi_temp_path /var/tmp/nginx/fastcgi 1 2;
</pre>

Large file uploads take some time to be processed by php-fpm, so you need to bump the Nginx default read timeout:

<pre>
fastcgi_read_timeout 300s;
</pre>

Set user and group for php-fpm in {{path|/etc/php7/php-fpm.d/www.conf}}:
<pre>
...
user = nginx
group = www-data
...
</pre>

{{Note|If you are serving serveral users make sure to tune the *''children'' settings in {{path|/etc/php7/php-fpm.d/www.conf}}}}

Also enable $PATH by uncommenting the following lines in {{path|/etc/php7/php-fpm.d/www.conf}}:

<pre>
...
env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp
...
</pre>

Make nginx user a member of the www-data group:
{{cmd|addgroup nginx www-data}}

Enable your website:
{{cmd|ln -s ../sites-available/mysite.mydomain.com /etc/nginx/sites-enabled/mysite.mydomain.com}}

The default configuration of nginx shows a 404 page. Therefore, we have to edit {{path|/etc/nginx/nginx.conf}}:
<pre>
...
# Includes virtual hosts configs.
# include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
...
</pre>

Start services:
{{cmd|rc-service php-fpm7 start
rc-service nginx start}}

Enable automatic startup of services:
{{cmd|rc-update add php-fpm7
rc-update add nginx}}

=== Lighttpd ===
Install the package:
{{cmd|apk add lighttpd php5-cgi}}

Make sure you have FastCGI enabled in {{pkg|lighttpd}}:
{{cat|/etc/lighttpd/lighttpd.conf|...
include "mod_fastcgi.conf"
...}}

Start up the webserver:
{{cmd|/etc/init.d/lighttpd start}}

{{tip|You might want to follow the [http://wiki.alpinelinux.org/wiki/Lighttpd_Https_access Lighttpd_Https_access] doc in order to configure lighttpd to use https ''(securing your connections to your nextcloud server)''.}}

Link {{pkg|nextcloud}} installation to web server directory:
{{cmd|ln -s /usr/share/webapps/nextcloud /var/www/localhost/htdocs}}

== Other settings ==
=== Hardening ===
Consider updating the variable <code>url.access-deny</code> in {{path|/etc/lighttpd/lighttpd.conf}} for additional security. Add <code>"config.php"</code> to the variable ''(that's where the database is stored)'' so it looks something like this:
{{cat|/etc/lighttpd/lighttpd.conf|...
url.access-deny {{=}} ("~", ".inc", "config.php")
...}}
Restart {{pkg|lighttpd}} to activate the changes:
{{cmd|/etc/init.d/lighttpd restart}}

=== Additional packages ===
Some large apps, such as pdfviewer, texteditor, notifications and videoplayer are in separate packages:
{{cmd|apk add nextcloud-pdfviewer nextcloud-texteditor nextcloud-notifications nextcloud-videoplayer}}

= Configure and use Nextcloud =
== Configure ==
Point your browser at <code><nowiki>https://mysite.mydomain.com</nowiki></code> and follow the on-screen instructions to complete the installation, supplying the database user and password created before.

== Hardening PostgreSQL ==
If you have chosen PGSQL backend, revoke CREATEDB privilege from 'mycloud' user:
{{cmd|psql -U postgres
ALTER ROLE mycloud NOCREATEDB;
\q}}

== Increase upload size ==
Default configuration for php is limited to 2Mb file size. You might want to increase that size by editing the {{path|/etc/php/php.ini}} and change the following values to something that suits you:
<pre>
upload_max_filesize = 2M
post_max_size = 8M
</pre>

== enable opcache for nginx/php7 ==
To increase performace install
{{cmd|apk add php7-opcache}}

Now uncomment/edit lines in /etc/php7/php.ini:
<pre>
...
opcache.enable=1
opcache.enable_cli=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128
opcache.save_comments=1
opcache.revalidate_freq=1
...
</pre>

Restart php-fpm7
{{cmd|rc-service php-fpm7 restart}}

== Clients ==
There are clients available for many platforms, Android included:
* http://nextcloud.org/sync-clients/ ''(nextcloud Sync clients)''
* http://nextcloud.org/support/android/ ''(Android client)''

[http://pkgs.alpinelinux.org/packages?name=nextcloud-client&branch=&repo=&arch=&maintainer= nextcloud-client] is currently available in the testing repo.

= Video Communication =
One of the major features of Nextcloud 11, available on Alpine 3.6 (currently edge) is a [https://nextcloud.com/webrtc/ WebRTC app], which relies on Spreed WebRTC server, which is available in the Alpine testing repository. Everything is still beta, so be aware of it :-). If you want a private video conferencing server install Nextcloud using Nginx and do the following (you can use Apache as well and follow the ''Apache config'' instructions [https://nextcloud.com/webrtc/ nextcloud.com]):

Put the following config in the ''server'' section of Nginx:
<pre>
# Spreed WebRTC
location ^~ /webrtc {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_buffering on;
proxy_ignore_client_abort off;
proxy_redirect off;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
}
</pre>

Put the following section in the ''http'' section of Nginx:
<pre>
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
</pre>

Reload Nginx:
{{cmd|rc-service nginx reload}}

Install Spreed WedRTC server (make sure you have the testing [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Packages_and_Repositories repository] enabled):
{{cmd|apk add spreed-web-server}}

Using the configuration file in ''/etc/spreed-webrtc/spreed-webrtc-server.conf'' follow the instructions at [https://nextcloud.com/webrtc/ nextcloud.com] to configure Spreed WebRTC server. Then start the server:
{{cmd|rc-service spreed-web-server start}}
{{cmd|rc-update add spreed-web-server}}

Install the ''Spreed video calls'' app in Nextcloud and enjoy your private video calls.

[[Category:Server]]

Alpine Linux:FAQ

2019-02-25T23:49:12Z

Aduty: /* How can I contribute? */

[[Image:filetypes.svg|64px|left|link=]]
This is a list of '''frequently asked questions''' about Alpine Linux.<br>
If your question is not answered on this page, use the search box above to find work in progress pages not linked here, or in case of no answer, edit this page and write down your question.
{{Tip| Prepare your question. Think it through. Make it simple and understandable.}}

=General=

To get oriented and learn what makes our distribution distinctive, see the [http://alpinelinux.org/about About page] or [[Alpine Linux:Overview|our more detailed overview]].

== I have found a bug, where can I report it? ==
You can report it on the [http://bugs.alpinelinux.org/ bugtracker].

== Are there any details about the releases available? ==
Yes, please check the [[Alpine Linux:Releases|Releases]] page.

== Alpine freezes during boot from Compact Flash, how can I fix? ==
Most Compact Flash card readers do not support proper DMA.<br>
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

== How can I contribute? ==
You can contribute by:
* Using the software and giving feedback.
* Documenting your [http://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]].
* In many other ways.
Please visit [[Contribute|Contribute page]] to read more about this topic.

Your contributions are highly appreciated.

== How do I remove the CDROM? ==
Since the modloop loopback device is on CDROM you cannot just run <code>eject</code>. You need to unmount the modloop first.<br>
Unmounting both the modloop and the CDROM in one step can be done by executing:
{{Cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the CDROM:
{{Cmd|eject}}

== Why don't I have man pages or where is the 'man' command? ==
The <code>man</code> command and man pages are not installed by default.

* First, install the {{pkg|man}} package:
: {{Cmd|apk add man}}
* Once that's done, install the documentation for the packages that you require man pages for.<br />(Keep in mind, however, it's possible that not all packages will have a corresponding documentation package.)
: {{Cmd|apk add ''package''-doc}}
: For example, say you installed {{Pkg|iptables}} and you now require its man pages:
: {{Cmd|apk add iptables-doc}}
<br />
In our example above, we installed the man pages (and other documentation) for <code>iptables</code>. We can now read it:
{{Cmd|man iptables}}

==Booting Alpine on an HP ML350 G6==
{{Note|This 'Booting Alpine on an HP ML350 G6' section, only applies to [http://www.alpinelinux.org/ Alpine Linux] 1.9.3 and earlier.}}
[http://bugs.alpinelinux.org/issues/228 Ticket 228] on [http://bugs.alpinelinux.org/ bugs.alpinelinux.org] includes a patch that disables the kernel module hpwdt by default.

Details: Kernel module for HP Watchdog Timer causes issues during boot. Solution is to create an overlay (ie {{path|hpwdt.apkovl.tar.gz}}) containing {{path|/etc/modprobe.d/hpwdt}} (which contains "blacklist hpwdt"), place that on some removable media (ie USB key) and insert that during boot process. This will insure that the offending module doesn't load and that the server will boot properly.

==My cron jobs don't run?==

Start service ''crond'' and add it to runlevel:

: {{cmd|rc-service crond start && rc-update add crond}}

After that the cron daemon is started automatically on system boot and executes the scripts placed in the folders under {{path|/etc/periodic}} - there's a {{path|15min}} folder, plus ones for {{path|hourly}}, {{path|daily}}, {{path|weekly}} and {{path|monthly}} scripts.

You can check whether your scripts are likely to run using the command:

: {{cmd|run-parts --test /etc/periodic/[foldername]}} - for example: ''run-parts --test /etc/periodic/15min''

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command : {{cmd|chmod a+x [scriptname]}}
* Make sure the first line of your script is :<pre>#!/bin/sh</pre>
* Do not put file extensions on your script names - this stops them from working; for example: {{path|myscript}} will run, but {{path|myscript.sh}} won't

== What is the difference between edge and stable releases? ==
Stable releases are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment.

[[Edge]] is more of a rolling-release, with the latest and greatest packages available in the online repositories.<br>
Occasionally, snapshot ISO images of the then-current state of [[edge]] are made and are available for download.<br>
Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

== What kind of release of Alpine Linux are available? ==
Please check the [[Alpine_Linux:Releases|Releases]] page for more information.

=Setup=

== What is the difference between 'sys', 'data', and 'diskless' installs when running setup-alpine (or setup-disk)? ==
'''sys:''' This mode is a traditional disk install. The following partitions will be created on the disk: /boot, / (filesystem root) and swap.<br>
This mode may be used for development boxes, desktops, virtual servers, etc.

'''data:''' This mode uses your disk(s) for data storage, not for the operating system. Only /var is created on disk. The system itself will run from tmpfs (RAM).

Use this mode if you only want to use the disk(s) for a mailspool, databases, logs, etc.

'''diskless:''' No disks are to be used. [[Alpine local backup]] may still be used in this mode.

These modes are explained further [[Installation#Basics|on the Installation page]].

== How can I install a custom firmware in a diskless system? ==

The modules and firmware are both special images which are mounted as read-only.<br>
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it.<br>
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

=Audio=

== How do I play my .ogg/.mp3 files? ==
First, the sound card should be recognized (you must have {{path|/dev/snd/*****}} files)

{{pkg|sox}}, {{pkg|mpg123}}, etc all use the oss sound driver, while Alpine uses ALSA drivers.<br>
So you need to load the snd-pcm-oss compatibility module.<br>
While you're at it, you might need {{pkg|aumix}} to turn up the sound volume
{{cmd|echo snd-pcm-oss >> /etc/modules
modprobe snd-pcm-oss
apk_add aumix sox
aumix (set volume settings)
play really_cool_song.mp3}}

= Time and timezones =

== How do I set the local timezone? ==

Starting in Alpine 2.2, setting the timezone can be done through the [[Setup-alpine|setup-alpine]] script, and no manual settings should be necessary.<br>
If you wish to edit the timezone after installation, run the [[Alpine_setup_scripts|setup-timezone]] script.

However, if you are using a previous version, please use the following steps:

/etc/timezone and the whole zoneinfo directory tree are not supported.
To set the timezone, set the TZ environment variable as specified in
http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap08.html
or you may also create an /etc/TZ file of a single line, ending with a
newline, containing the TZ setting. For example
echo CST6CDT > /etc/TZ
''Source: http://www.uclibc.org/downloads/Glibc_vs_uClibc_Differences.txt''

For more information, see how other uClibc-based distributions do this:
* http://leaf.sourceforge.net/doc/buci-tz3.html
* http://www.sonoracomm.com/index.php?option=com_content&task=view&id=107&Itemid=32

For a more complete list of timezones, please see: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones

== OpenNTPD reports an error with "adjtime" ==
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps.<br>
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

== Using a cron job to keep the time in sync ==
Add the following to {{path|/etc/periodic/daily}} (or use another folder under the {{path|/etc/periodic}} heirarchy if you want to run the script more/less frequently)

Example: file called {{path|do-ntp}}
<pre>
#!/bin/sh
ntpd -d -q -n -p uk.pool.ntp.org</pre>

This queries the uk time server pool - you can modify this to suit your localisation, or just use ''pool.ntp.org''. More info here: [http://www.pool.ntp.org/zone/@ http://www.pool.ntp.org/zone/@]

== Windows clients reports an error when trying to sync ==
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your {{pkg|openntpd}} server.

Only thing to do is wait, do something else for 15-20mins and then check.

= Packages =
== Can you build an apk package for ...? ==
Yes, we probably can.<br>
Please create an [https://bugs.alpinelinux.org/projects/alpine/issues/new issue] in the [https://bugs.alpinelinux.org bugtracker]. Mark it as "feature" and include a short description (one-line), an url for the home page, and an url for the source package.

== How can I build my own package? ==
Please see the [[Creating an Alpine package]] page.

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running package related tools, check your {{path|/etc/apk/repositories}} file if an entry points to {{path|.../v2.4/testing/}}. This directory is gone.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

== What does "required by: world[$pkgname]" mean? ==

It means that the package you try to install does not exist in the repositories you have configured in <code>/etc/apk/repositories</code>. Maybe you forgot to add community, testing or unmaintained to /etc/apk/repositories?

== How can i find out if a certain package exists in alpine? ==

If you want to only search repositories you have configured in /etc/apk/repositories, then <code>apk search $pkgname</code> should get you sorted. If you want to search all repositories have a look at the [https://pkgs.alpinelinux.org/ online pkg oracle]

= Dynamic DNS =
== How do I schedule a regular dynamic DNS update? ==
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ez-ipupdate.conf}} with contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && \<br>/bin/date >> /var/log/ez-ipupdate && \<br>ez-ipupdate --config-file /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid \<br> --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

= Terminal =

== How to enable/fix colors for git? ==

The problem is not in git itself or terminal, but in the <tt>less</tt> command.
Busybox’s <tt>less</tt> doesn’t support <tt>-r</tt> (<tt>--raw-control-chars</tt>) and <tt>-R</tt> (<tt>--RAW-CONTROL-CHARS</tt>) options.

The simplest (yet not ideal) solution is to install GNU less:

{{cmd|apk add less}}

Alpine Linux:FAQ

2019-02-25T23:46:14Z

Aduty: /* How do I schedule a regular dynamic DNS update? */

[[Image:filetypes.svg|64px|left|link=]]
This is a list of '''frequently asked questions''' about Alpine Linux.<br>
If your question is not answered on this page, use the search box above to find work in progress pages not linked here, or in case of no answer, edit this page and write down your question.
{{Tip| Prepare your question. Think it through. Make it simple and understandable.}}

=General=

To get oriented and learn what makes our distribution distinctive, see the [http://alpinelinux.org/about About page] or [[Alpine Linux:Overview|our more detailed overview]].

== I have found a bug, where can I report it? ==
You can report it on the [http://bugs.alpinelinux.org/ bugtracker].

== Are there any details about the releases available? ==
Yes, please check the [[Alpine Linux:Releases|Releases]] page.

== Alpine freezes during boot from Compact Flash, how can I fix? ==
Most Compact Flash card readers do not support proper DMA.<br>
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

== How can I contribute? ==
You can contribute by:
* using the software and giving feedback
* by documenting your [http://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]]
* in many other ways
Please visit [[Contribute|Contribute page]] to read more about this topic.

Your contributions are highly appreciated.

== How do I remove the CDROM? ==
Since the modloop loopback device is on CDROM you cannot just run <code>eject</code>. You need to unmount the modloop first.<br>
Unmounting both the modloop and the CDROM in one step can be done by executing:
{{Cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the CDROM:
{{Cmd|eject}}

== Why don't I have man pages or where is the 'man' command? ==
The <code>man</code> command and man pages are not installed by default.

* First, install the {{pkg|man}} package:
: {{Cmd|apk add man}}
* Once that's done, install the documentation for the packages that you require man pages for.<br />(Keep in mind, however, it's possible that not all packages will have a corresponding documentation package.)
: {{Cmd|apk add ''package''-doc}}
: For example, say you installed {{Pkg|iptables}} and you now require its man pages:
: {{Cmd|apk add iptables-doc}}
<br />
In our example above, we installed the man pages (and other documentation) for <code>iptables</code>. We can now read it:
{{Cmd|man iptables}}

==Booting Alpine on an HP ML350 G6==
{{Note|This 'Booting Alpine on an HP ML350 G6' section, only applies to [http://www.alpinelinux.org/ Alpine Linux] 1.9.3 and earlier.}}
[http://bugs.alpinelinux.org/issues/228 Ticket 228] on [http://bugs.alpinelinux.org/ bugs.alpinelinux.org] includes a patch that disables the kernel module hpwdt by default.

Details: Kernel module for HP Watchdog Timer causes issues during boot. Solution is to create an overlay (ie {{path|hpwdt.apkovl.tar.gz}}) containing {{path|/etc/modprobe.d/hpwdt}} (which contains "blacklist hpwdt"), place that on some removable media (ie USB key) and insert that during boot process. This will insure that the offending module doesn't load and that the server will boot properly.

==My cron jobs don't run?==

Start service ''crond'' and add it to runlevel:

: {{cmd|rc-service crond start && rc-update add crond}}

After that the cron daemon is started automatically on system boot and executes the scripts placed in the folders under {{path|/etc/periodic}} - there's a {{path|15min}} folder, plus ones for {{path|hourly}}, {{path|daily}}, {{path|weekly}} and {{path|monthly}} scripts.

You can check whether your scripts are likely to run using the command:

: {{cmd|run-parts --test /etc/periodic/[foldername]}} - for example: ''run-parts --test /etc/periodic/15min''

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command : {{cmd|chmod a+x [scriptname]}}
* Make sure the first line of your script is :<pre>#!/bin/sh</pre>
* Do not put file extensions on your script names - this stops them from working; for example: {{path|myscript}} will run, but {{path|myscript.sh}} won't

== What is the difference between edge and stable releases? ==
Stable releases are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment.

[[Edge]] is more of a rolling-release, with the latest and greatest packages available in the online repositories.<br>
Occasionally, snapshot ISO images of the then-current state of [[edge]] are made and are available for download.<br>
Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

== What kind of release of Alpine Linux are available? ==
Please check the [[Alpine_Linux:Releases|Releases]] page for more information.

=Setup=

== What is the difference between 'sys', 'data', and 'diskless' installs when running setup-alpine (or setup-disk)? ==
'''sys:''' This mode is a traditional disk install. The following partitions will be created on the disk: /boot, / (filesystem root) and swap.<br>
This mode may be used for development boxes, desktops, virtual servers, etc.

'''data:''' This mode uses your disk(s) for data storage, not for the operating system. Only /var is created on disk. The system itself will run from tmpfs (RAM).

Use this mode if you only want to use the disk(s) for a mailspool, databases, logs, etc.

'''diskless:''' No disks are to be used. [[Alpine local backup]] may still be used in this mode.

These modes are explained further [[Installation#Basics|on the Installation page]].

== How can I install a custom firmware in a diskless system? ==

The modules and firmware are both special images which are mounted as read-only.<br>
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it.<br>
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

=Audio=

== How do I play my .ogg/.mp3 files? ==
First, the sound card should be recognized (you must have {{path|/dev/snd/*****}} files)

{{pkg|sox}}, {{pkg|mpg123}}, etc all use the oss sound driver, while Alpine uses ALSA drivers.<br>
So you need to load the snd-pcm-oss compatibility module.<br>
While you're at it, you might need {{pkg|aumix}} to turn up the sound volume
{{cmd|echo snd-pcm-oss >> /etc/modules
modprobe snd-pcm-oss
apk_add aumix sox
aumix (set volume settings)
play really_cool_song.mp3}}

= Time and timezones =

== How do I set the local timezone? ==

Starting in Alpine 2.2, setting the timezone can be done through the [[Setup-alpine|setup-alpine]] script, and no manual settings should be necessary.<br>
If you wish to edit the timezone after installation, run the [[Alpine_setup_scripts|setup-timezone]] script.

However, if you are using a previous version, please use the following steps:

/etc/timezone and the whole zoneinfo directory tree are not supported.
To set the timezone, set the TZ environment variable as specified in
http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap08.html
or you may also create an /etc/TZ file of a single line, ending with a
newline, containing the TZ setting. For example
echo CST6CDT > /etc/TZ
''Source: http://www.uclibc.org/downloads/Glibc_vs_uClibc_Differences.txt''

For more information, see how other uClibc-based distributions do this:
* http://leaf.sourceforge.net/doc/buci-tz3.html
* http://www.sonoracomm.com/index.php?option=com_content&task=view&id=107&Itemid=32

For a more complete list of timezones, please see: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones

== OpenNTPD reports an error with "adjtime" ==
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps.<br>
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

== Using a cron job to keep the time in sync ==
Add the following to {{path|/etc/periodic/daily}} (or use another folder under the {{path|/etc/periodic}} heirarchy if you want to run the script more/less frequently)

Example: file called {{path|do-ntp}}
<pre>
#!/bin/sh
ntpd -d -q -n -p uk.pool.ntp.org</pre>

This queries the uk time server pool - you can modify this to suit your localisation, or just use ''pool.ntp.org''. More info here: [http://www.pool.ntp.org/zone/@ http://www.pool.ntp.org/zone/@]

== Windows clients reports an error when trying to sync ==
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your {{pkg|openntpd}} server.

Only thing to do is wait, do something else for 15-20mins and then check.

= Packages =
== Can you build an apk package for ...? ==
Yes, we probably can.<br>
Please create an [https://bugs.alpinelinux.org/projects/alpine/issues/new issue] in the [https://bugs.alpinelinux.org bugtracker]. Mark it as "feature" and include a short description (one-line), an url for the home page, and an url for the source package.

== How can I build my own package? ==
Please see the [[Creating an Alpine package]] page.

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running package related tools, check your {{path|/etc/apk/repositories}} file if an entry points to {{path|.../v2.4/testing/}}. This directory is gone.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

== What does "required by: world[$pkgname]" mean? ==

It means that the package you try to install does not exist in the repositories you have configured in <code>/etc/apk/repositories</code>. Maybe you forgot to add community, testing or unmaintained to /etc/apk/repositories?

== How can i find out if a certain package exists in alpine? ==

If you want to only search repositories you have configured in /etc/apk/repositories, then <code>apk search $pkgname</code> should get you sorted. If you want to search all repositories have a look at the [https://pkgs.alpinelinux.org/ online pkg oracle]

= Dynamic DNS =
== How do I schedule a regular dynamic DNS update? ==
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ez-ipupdate.conf}} with contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && \<br>/bin/date >> /var/log/ez-ipupdate && \<br>ez-ipupdate --config-file /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid \<br> --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

= Terminal =

== How to enable/fix colors for git? ==

The problem is not in git itself or terminal, but in the <tt>less</tt> command.
Busybox’s <tt>less</tt> doesn’t support <tt>-r</tt> (<tt>--raw-control-chars</tt>) and <tt>-R</tt> (<tt>--RAW-CONTROL-CHARS</tt>) options.

The simplest (yet not ideal) solution is to install GNU less:

{{cmd|apk add less}}

Installation

2019-02-25T23:43:19Z

Aduty: /* Basics */

The following information will assist you with the installation of [http://alpinelinux.org/about Alpine Linux].
[[Image:hdd_mount.png|left|link=]]
<br />

== Installation Quick-Start in 3 Easy Steps ==
<div style="float:left; font-size:30px; font-weight:bold;">
1st
</div>
<div style="margin-left:65px; background-color:#EDF2F2; border-style:solid; border-color:#6F7C91; border-width:0px; border-left-width:5px; min-height:55px; padding:5px;">
[http://alpinelinux.org/downloads Download] one of the latest stable-release ISOs. Then compare the image's checksum to the one in the corresponding checksum file (<code>*.sha256</code>) and verify its GPG signature.
</div>

<div style="float:left; font-size:30px; font-weight:bold;">
2nd
</div>
<div style="margin-left:65px; background-color:#E0E9E9; border-style:solid; border-color:#606A82; border-width:0px; border-left-width:5px; min-height:55px; padding:5px;">
If you have a CD drive from which you can boot, then [[Burning ISOs|burn the ISO onto a blank CD]] using your favorite CD burning software. Else [[Create a Bootable USB|create a bootable USB drive]].
</div>

<div style="float:left; font-size:30px; font-weight:bold;">
3rd
</div>
<div style="margin-left:65px; background-color:#9faecc; border-style:solid; border-color:#324065; border-width:0px; border-left-width:5px; min-height:55px; padding:5px;">
Boot from the CD or USB drive, login as root with no password, and voilà! Enjoy Alpine Linux!
</div>

{{Clear}}
One of the [[Installation#Post-Install|first commands you might want to use]] is <code>[[setup-alpine]]</code>.

== Installation Handbook ==
=== Basics ===
Alpine can be used in any of three modes:
<dl>
<dt>diskless mode
<dd>You'll boot from a read-only medium such as the installation CD, a [[Create a Bootable USB|USB drive]], or a [[Create a Bootable Compact Flash|Compact Flash card]]. {{Tip| To prepare either a USB or Compact Flash card, you can use the <code>[[setup-bootable]]</code> script; see the pages linked above for details.}} When you use Alpine in this mode, you need to use [[Alpine local backup|Alpine Local Backup (lbu)]] to save your modifications between reboots. That requires some writable medium, usually removable. If your boot medium is, for example, a USB drive, you can save modifications there; you don't need a separate partition or drive. See also [[Local APK cache]].
{{Note| When the <code>[[setup-alpine]]</code> script asks for a disk, say "none". It will then prompt whether you'd like to preserve modifications on any writable medium.}}
<dt>data mode
<dd>As in diskless mode, your OS is run from a read-only medium. However, here a writable partition (usually on a hard disk) is used to store the data in {{Path|/var}}. That partition is accessed directly, rather than copied into a tmpfs; so this is better-suited to uses where large amounts of data need to be preserved between reboots. {{Note| The <code>[[setup-alpine]]</code> script handles installing Alpine in this mode, too, when you supply a writable partition instead of "none", and request mode "data".}} This mode may be used for mailspools, database and log servers, and so on.
<dt>sys mode
<dd>This is a [[Install to disk|traditional hard-disk install]] (see link for details).  Both the boot system and your modifications are written to the hard disk in a standard Linux hierarchy. {{Note| The <code>[[setup-alpine]]</code> script handles installing Alpine in this mode, too, when you supply a writable partition instead of "none", and request mode "sys". By default, it will create three partions on your disk for {{Path|/boot}}, {{Path|/}}, and {{Path|swap}}; however you can also [[Setting up disks manually|partition your disk manually]].
}} This mode may be used for [[Desktops|desktops]], development boxes, and virtual servers.

</dl>

=== Advanced ===
* [[Create UEFI boot USB]]
* [[Tutorials_and_Howtos#Storage|Setting up storage with RAID, LVM, LUKS encryption, iSCSI, or suchlike]]
* [[Setting up disks manually]]
* [[Partitioning and Bootmanagers]]
* [[Migrating data]]
* Details about [[Alpine setup scripts]]

* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Create A VirtualBox Guest with Grub and XFS]]
* [[Replacing non-Alpine Linux with Alpine remotely]]



* [[Bootstrapping Alpine Linux]]


* [[Installing Alpine Linux in a chroot]]
* [[Install Alpine on LXC]]
* [[Install Alpine on LXD|Install Alpine on Ubuntu with LXD]]
* Install Alpine on [[Install Alpine on VirtualBox|VirtualBox]], [[Install Alpine on VMware|VMware]], [[Install Alpine on coLinux|coLinux]], [[Qemu]],  [[Install Alpine on Amazon EC2|Amazon EC2]], or [[Install Alpine on Rackspace|RackSpace]]

* [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
* [[Xen Dom0 on USB or SD]]
* [[Create Alpine Linux PV DomU]]
* [[Xen LiveCD]]

* [[Setting up a basic vserver]]
* [[Setting up the build environment on HDD]]
* [[Setting up a compile vserver]] for official or for [[Setting up a compile vserver for third party packages|third party]] packages


=== Post-Install ===



* [[Tutorials_and_Howtos#Networking|Setting up Networking]]
* [[Alpine Linux package management|Package Management (apk)]] ''(How to add/remove packages on your Alpine)''

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation|Back Up a Flash Memory ("diskless mode") 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)''
* [[setup-acf]] ''(Configures ACF (webconfiguration) so you can manage your box through https)''
* [[Hosting services on Alpine]]''(Links to several mail/web/ssh server setup pages)''
* [[Changing passwords for ACF|Changing passwords]]


* [[Setting the timezone]] ''(Not needed for the default musl- or uClibc-based installs)''

=== Further Help and Information ===
* [[FAQ|FAQs]]
* [[Tutorials and Howtos]]
* [[Contribute|How to Contribute]]
* [[Developer Documentation]]

[[Category:Installation]]

LVM on LUKS

2019-02-25T21:39:37Z

Aduty: /* Creating the Partition Layout */

= Introduction =

This documentation describes how to set up Alpine Linux using a logical volume (LV), that is installed in an encrypted partition. To encrypt the partition the logical volume manager (LVM) the volume group (VG) is installed in, the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly.

== Hard Disk Device Name ==

The following documentation uses the <code>vda</code> device as installation destination. If your environment uses a different device name for your hard disk, use the corresponding device names in the examples.

= Setting up Alpine Linux Using LVM on Top of a LUKS Partition =

To install Alpine Linux in logical volumes running on top of a LUKS encrypted partition, you cannot use the [[Installation|official installation]] procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.

== Preparing the Temporary Installation Environment ==

Before you begin to install Alpine Linux, prepare the temporary environment:

{{Note|All settings in this section apply only to the temporary environment and not to the later installed Alpine Linux on your hard disk.}}

* Boot the latest Alpine Linux Installation CD.

* At the login prompt, use the <code>root</code> user without password to log in.

* Optionally, set the keyboard language:

# setup-keymap

: The default keyboard mapping is <code>us-us</code>

* Configure the network interface:

# setup-interfaces

: If you set a static IP address, additionally configure DNS be able to resolve host names:

# setup-dns

* Enable the network interface. For example:

# ifup eth0

* Set an apk repository and update the cache:

# setup-apkrepos
# apk update

* Install the following packages required to set up LVM and LUKS:

# apk add haveged lvm2 cryptsetup e2fsprogs syslinux

: Optionally, you can install a different editor, such as <code>nano</code>, to edit files in later steps if you do not want to use VI.

* Optionally, start the <code>haveged</code> service for unpredictable random numbers used for encryption:

# rc-service haveged start

== Creating the Partition Layout ==

Linux requires an unencrypted <code>/boot/</code> partition to boot. You can assign the remaining space for the encrypted LVM physical volume (PV).

* Start the <code>fdisk</code> utility to set up partitions:

# fdisk /dev/vda

:* Create the <code>/boot/</code> partition:
::* Enter <code>n</code> → <code>p</code> → <code>1</code> → <code>1</code> → <code>+100m</code> to create a new 100 MB primary partition.

:* Set the <code>/boot/</code> partition active:
::* Enter <code>a</code> → <code>1</code>.

:* Create the LVM PV partition:
::* Enter <code>n</code> → <code>p</code> → <code>2</code> to start creating the next partition. Press <code>Enter</code> to select the default start cylinder. Enter the size of partition. For example, <code>512m</code> for 512 MB or <code>5g</code> for 5 GB. Alternatively press <code>Enter</code> to set the maximum available size.

:* Set the partition type for the LVM PV:
::* Enter <code>t</code> → <code>2</code> → <code>8e</code>

:* To verify the settings, press <code>p</code>. The output shows, for example:

Device Boot Start End Blocks Id System
/dev/vda1 * 1 100 50368+ 83 Linux
/dev/vda2 101 10402 5192208 8e Linux LVM

* Press <code>w</code> to save the changes.

* Optionally, wipe the LVM PV partition with random values:

# haveged -n 0 | dd of=/dev/vda2

: Depending on the size of the partition, this process can take several minutes to hours.

== Encrypting the LVM Physical Volume Partition ==

* To encrypt the partition which will later contain the LVM PV:

# cryptsetup luksFormat /dev/vda2

:{{Note|Alpine Linux uses the <code>en-us</code> keyboard mapping when prompting for the password to encrypt the partition at boot time. If you changed the keyboard map in the temporary environment, the password you enter during encrypting the partition in this step, may not match the password you will enter during the system boots.}}
: If you prefer setting an individual hashing algorithm and hashing schema:
:* To run a benchmark:

# cryptsetup benchmark

:* To encrypt the partition using individual settings, enter, for example:

# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash whirlpool --iter-time 5000 --use-random luksFormat /dev/vda2

== Creating the Logical Volumes and File Systems ==

* Open the LUKS partition:

# cryptsetup open --type luks /dev/vda2 lvmcrypt

* Create the PV on <code>/dev/vda</code>:

# pvcreate /dev/mapper/lvmcrypt

* Create the <code>vg0</code> LVM VG in the <code>/dev/mapper/lvmcrypt</code> PV:

# vgcreate vg0 /dev/mapper/lvmcrypt

* Create the LVs:

: In the following you will create a LV for the root partition. However, you can use the same command with a different LV name to create further LVs for other mount points you want to create.

:* To create a 2 GB LV named <code>root</code> in the <code>vg0</code> VG:

# lvcreate -L 2G vg0 -n root

: Create a 512 MB swap LV:

# lvcreate -L 512M vg0 -n swap

* The LVs created in the previous steps are automatically marked active. To verify, enter:

# lvscan

: Format the <code>root</code> LV using the ext4 file system:

# mkfs.ext4 /dev/vg0/root

: If you created further LVs in the previous step, create the file systems on them using the same command with the path to the LV.

* Format the swap LV:

# mkswap /dev/vg0/swap

* Format the <code>/dev/vda1</code> device for the <code>/boot/</code> partition using the ext4 file system:

# mkfs.ext4 /dev/vda1

== Mounting the File Systems ==

Before you can install Alpine Linux, you must mount the partitions and LVs:

* Mount the root LV to the <code>/mnt/</code> directory:

# mount -t ext4 /dev/vg0/root /mnt/

* Create <code>/mnt/boot/</code> directory and mount the <code>/dev/vda1</code> partition in this directory:

# mkdir /mnt/boot/
# mount -t ext4 /dev/vda1 /mnt/boot/

: If you created further partitions or LVs, create the mount points within the <code>/mnt/</code> directory and mount the devices.

== Installing Alpine Linux ==

In this step you will install Alpine Linux in the <code>/mnt/</code> directory, which contains the mounted file system structure:

* Install Alpine Linux:

# setup-disk -m sys /mnt/

: The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the <code>fstab</code> file, which are currently mounted in the <code>/mnt/</code> directory.

: {{Note|The automatic writing of the master boot record (MBR) fails in this step. You will write the MBR later manually to the disk.}}

* To enable the operating system to decrypt the PV at boot time, create the <code>/mnt/etc/crypttab</code> file. Enter the following line into the file to decrypt the <code>/dev/vda2</code> partition using the <code>luks</code> module and map it to the <code>lvmcrypt</code> name:

lvmcrypt /dev/vda2 none luks

* The swap LV is not automatically added to the <code>fstab</code> file. To add it manually, add the following line to the <code>/mnt/etc/fstab</code> file:

/dev/vg0/swap swap swap defaults 0 0

* Edit the <code>/mnt/etc/mkinitfs/mkinitfs.conf</code> file and append the <code>cryptsetup</code> module to the <code>features</code> parameter:

features="ata base ide scsi usb virtio ext4 lvm <u>cryptsetup</u>"

* Rebuild the initial RAM disk:

# mkinitfs -c /mnt/etc/mkinitfs/mkinitfs.conf -b /mnt/ $(ls /mnt/lib/modules/)

: The command uses the settings from the <code>mkinitfs.conf</code> file set in the <code>-c</code> parameter to generate the RAM disk. The command is executed in the <code>/mnt/</code> directory and the RAM disk is generated using the modules for the installed kernel. Without setting the kernel version using the <code>$(ls /mnt/lib/modules/</code>) option, <code>mkinitfs</code> tries to generate the RAM disk using the kernel version installed in the temporary environment, which can differ from the latest one installed by the <code>setup-disk</code> utility.

* Edit the <code>/mnt/etc/update-extlinux.conf</code> file and append the following kernel options to the <code>default_kernel_opts</code> parameter:

default_kernel_opts="... <u>cryptroot=/dev/vda2 cryptdm=lvmcrypt</u>"

: The <code>cryptroot</code> parameter sets the name of the device that contains the root file system. The <code>cryptdm</code> parameter sets the name of the mapping previously set in the <code>crypttab</code> file.

* Because the <code>update-extlinux</code> utility operators only on the <code>/boot/</code> directory, temporarily change the root to the <code>/mnt/</code> directory and update the boot loader configuration:

# chroot /mnt/
# update-extlinux
# exit

: Ignore the errors the <code>update-extlinux</code> utility displays.

* Write the MBR to the <code>/dev/vda</code> device:

# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/vda

== Unmounting the Volumes and Partitions ==

* Umount <code>/mnt/boot/</code> and <code>/mnt/</code>:

# umount /mnt/boot/
# umount /mnt/

: {{Note|If you mounted further partitions or LVs below <code>/mnt/</code>, you must first unmount all of them before you can unmount <code>/mnt/</code>.}}

* Disable the swap partition:

# swapoff -a

* Deactivate the VG:

# vgchange -a n

* Close the <code>lvmcrypt</code> device:

# cryptsetup luksClose lvmcrypt

* Reboot the system:

# reboot

= Troubleshooting =

== General Procedure ==

In case your system fails to boot, you can verify the settings and fix incorrect configurations:

* [[#Preparing_the_Temporary_Installation_Environment|Prepare the temporary installation environment]]

* Activate the VGs:

# vgchange -a y

* [[#Mounting_the_File_Systems|Mount the file systems]]

* Verify that you run the steps described in the [[#Installing_Alpine_Linux|Installing Alpine Linux]] section correctly. Update the configuration if necessary.

* [[#Unmounting_the_Volumes_and_Partitions|Unmount the volumes and partitions]]

= Hardening =

* To harden, you should disable DMA[https://old.iseclab.org/papers/acsac2012dma.pdf] and install a hardened version of AES (TRESOR[https://www1.informatik.uni-erlangen.de/tresor] or Loop-Amnesia[http://moongate.ydns.eu/amnesia.html]) since by default cryptsetup with luks uses AES by default.
* Disable DMA in the BIOS and set the password for the BIOS according to Wikipedia.[https://en.wikipedia.org/wiki/DMA_attack]
* Blacklist kernel modules that use DMA and any unused expansion modules (FireWire, CardBus, ExpressCard, Thunderbolt, USB 3.0, PCI Express and hotplug modules) that use DMA.

[[Category:Storage]]
[[Category:Security]]

Include:Abump

2019-02-25T05:53:15Z

Aduty:

The tool <tt>abump</tt> is a utility to bump pkgver in APKBUILD files if the package gets an update to a newer upstream release.

{{Cmd|<nowiki>abump [-hR]</nowiki>}}

'''abump options'''

* '''-h''' Show this help
* '''-R''' Run abuild with -R for recursive building
* '''-k''' Keep existing packages

[[Category:Development]]

Abuild and Helpers

2019-02-25T05:47:50Z

Aduty:

The abuild package provides scripts you need when creating packages for Alpine Linux. The abuild package and its friends are installed automatically along with the <tt>alpine-sdk</tt> package.

{{Cmd|apk add alpine-sdk}}

The [http://git.alpinelinux.org/cgit/abuild.git/tree/ git repository] always contains the latest version of the scripts, example-files, and makefiles.

== Building and maintaining packages ==

=== abuild ===
{{:Include:Abuild}}

=== abump ===
{{:Include:Abump}}

=== apkgrel ===

{{:Include:Apkgrel}}

== Generating new APKBUILDs ==

=== newapkbuild ===
To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file in the given directory, and fill some variables if those are provided.

{{:Include:Newapkbuild}}

=== apkbuild-cpan ===
{{:Include:Apkbuild-cpan}}

=== apkbuild-pypi ===
{{:Include:Apkbuild-pypi}}

== Signing packages and indexes ==

=== abuild-sign ===
{{:Include:Abuild-sign}}

=== abuild-tar ===
{{:Include:Abuild-tar}}

=== buildrepo ===
{{:Include:Buildrepo}}

== Setting up the build environment ==

=== abuild-keygen ===
{{:Include:Abuild-keygen}}

=== buildlab ===
See the [[Buildlab|buildlab]] page.

Abuild and Helpers

2019-02-25T05:41:41Z

Aduty:

The abuild package provides scripts you need when creating packages for Alpine Linux. The abuild and its friends are installed automatically along with the <tt>alpine-sdk</tt> package.

{{Cmd|apk add alpine-sdk}}

The [http://git.alpinelinux.org/cgit/abuild.git/tree/ git repository] always contains the latest version of the scripts, example-files, and makefiles.

== Building and maintaining packages ==

=== abuild ===
{{:Include:Abuild}}

=== abump ===
{{:Include:Abump}}

=== apkgrel ===

{{:Include:Apkgrel}}

== Generating new APKBUILDs ==

=== newapkbuild ===
To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file in the given directory, and fill some variables if those are provided.

{{:Include:Newapkbuild}}

=== apkbuild-cpan ===
{{:Include:Apkbuild-cpan}}

=== apkbuild-pypi ===
{{:Include:Apkbuild-pypi}}

== Signing packages and indexes ==

=== abuild-sign ===
{{:Include:Abuild-sign}}

=== abuild-tar ===
{{:Include:Abuild-tar}}

=== buildrepo ===
{{:Include:Buildrepo}}

== Setting up the build environment ==

=== abuild-keygen ===
{{:Include:Abuild-keygen}}

=== buildlab ===
See the [[Buildlab|buildlab]] page.