Alpine Linux - User contributions [en]

Installing Alpine on HDD overwriting everything

2011-11-01T16:07:37Z

Bess: updated so it's correct for alpine mini 2.3.0

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

The following is meant to be an absolute newbie guide

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

=== Continue Setting up your Computer ===

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

Alpine Package Keeper

2011-10-03T22:50:16Z

Bess: /* Local Cache */ added line to show how to enable local cache on HDD install

= Alpine Linux Package Management =

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
<br />
'''apk''' is the tool used to install, upgrade, or delete software on a running sytem.<br />
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [http://git.alpinelinux.org/cgit/apk-tools.git apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

The '''apk''' tool has the following applets:

{|
| [[#Add a Package|add]]
| Add new packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Info on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache Maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|}

== Quickstart Guide ==

=== Packages and Repositories ===

Software packages for Alpine Linux are digitally signed tar.gz archives containing the programs, configuration files, and dependency metadata. They have the extension "*.apk", and are often called "a-packs"

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named APKINDEX.tar.gz to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in <tt>/etc/apk/repositories</tt>, one repository per line. If you booted from USB stick (<tt>/media/sda1</tt>) or CD-ROM (<tt>/media/cdrom</tt>), your repository file probably looks like this:

<pre>
/media/sda1/apks/
</pre>

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

<pre>
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.1/main
https://dl-3.alpinelinux.org/alpine/v2.1/main
ftp://dl-3.alpinelinux.org/alpine/v2.1/main
</pre>

{{note|Currently there are no public https or ftp repositories. The protocols are available for local repositories}}

=== Update the Package list ===

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the APKINDEX.tar.gz from each repository and stores it in the local cache, typically <tt>/var/lib/apk</tt> or <tt>/etc/apk/cache</tt>.

{{Cmd|apk update}}
<pre>
fetch http://dl-3.alpinelinux.org/alpine/v2.1/main/APKINDEX.tar.gz
</pre>

{{Tip|If using remote repositories, it is a good idea to do an '''update''' just before doing an '''add''' or '''upgrade''' command. That way you know you are using the latest software available}}

=== Add a Package ===

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{cmd|apk add openssh
apk add openssh openntp vim}}

=== Remove a Package ===

Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

=== Upgrade a Running System ===

To upgrade ''all'' the packages of a running system, use '''upgrade'''

{{cmd|apk update
apk upgrade
}}

To upgrade only a few packages, use the '''add''' command with the ''-u'' parameter:

{{cmd|apk update
apk add -u busybox
}}

{{Note|Remember that when you reboot your machine, the remote repository will not be available until after networking is started. This means packages newer than your local boot media will likely not be installed after a reboot. To make an "upgrade" persist over a reboot, use a [[#Local Cache|local cache]].}}

=== Search for Packages ===

The '''search''' command searches the repository Index files for installable packages.

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description: {{cmd|apk search -v -d 'NTP' }}

=== Info on Packages ===

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information); or all information is displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package
* The '''webpage''' where the application is hosted
* The '''size''' the package will require once installed (in bytes)
* What packages are required to use this one ('''depends''')
* What packages require this one to be installed ('''required by''')
* The '''contents''' of the package
* Any '''triggers''' this package sets. Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}
== Additional apk Commands ==

In progress...

== Local Cache ==

Alpine Linux needs to be able to pull packages from local media on boot. (You can't download packages from the net before you have a network connection.) Using remote repositories presents a problem. If the config files have been modified for a newer version of a package, and the older package is on local media, all sorts of fun can result.

The solution is a local cache of updated packages. This cache can be stored on any r/w media, typically the same location as the apkovl.

=== To Enable Local Cache on HDD install ===
If you've installed Alpine to your hard drive, then run {{Cmd| mkdir /etc/apk/cache }}

=== To Enable Local Cache ===

# Create a '''cache''' directory on the device you store your lbu backups (typically, <code>/dev/sda1</code>.) {{Cmd| mkdir /media/sda1/cache }}
{{Tip|If you get an error that says "mkdir: can't create directory '/media/usbdisk/cache': Read-only file system", then you probably need to remount your disk read-write temporarily. Try {{Cmd|mount -o remount,rw /media/sda1}} and then don't forget to run {{Cmd|mount -o remount,ro /media/sda1}} when you are done with the following commands}}
# Create a symlink to this directory from <code>/etc/apk/cache</code>. {{Cmd|ln -s /media/sda1/cache /etc/apk/cache}}
# Run an lbu commit to save the change (<code>/etc/apk/cache</code> is in <code>/etc</code> and is automatically backed up.) {{Cmd|lbu commit}}
# Done. Now whenever you run an apk command that pulls a new package from a remote repository, The package is stored on your local media. On startup, Alpine Linux will check the local cache for new packages, and will install them in preference.

So you now have a run-from-RAM distro that can do a '''yum upgrade''' or '''apt-get dist-upgrade'''

=== Cache Maintenance ===

Over time, newer packages will replace older ones; the cache directory will contain all older versions of packages.

==== Delete Old Packages ====
To clean out older versions of packages, run the '''clean''' command. {{cmd|apk cache clean}} or to see what is deleted {{cmd|apk -v cache clean}}

==== Download Missing Packages ====
If you accidentally delete packages from the cache directory, you can make sure they are there with the '''download''' command, {{cmd|apk cache download}}

==== Delete and Download In One Step ====
You can combine the two steps into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|apk cache -v sync}}

==== Automatically Cleaning Cache on Reboot ====
To automatically attempt to validate your cache on reboot, you can add the above command to the <code>/etc/conf.d/local</code> script, in the <code>stop</code> stanza:

local_stop() {
# This is a good place to unload any misc.
# programs you started above.

# verify the local cache on shutdown
apk cache -v sync

# We should always return 0
return 0
}

{{Tip|Usually the only time you need to reboot is when things have gone horribly wrong; so this is a "best effort" to cover forgetting to sync the cache; It is much better to run '''sync''' immediately after adding or upgrading packages.}}

== Advanced APK Usage ==

=== Holding a specific package back ===

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

Installing Alpine on HDD overwriting everything

2011-10-03T22:30:53Z

Bess: updated so it's correct for alpine mini 2.2.3.

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

The following is meant to be an absolute newbie guide

* Burn the Alpine ISO image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text '''login:''' to appear, type '''root''' and press enter.
* Run the '''setup-alpine''' script
** Choose your keyboard, as an example, I chose '''us'''
*** Then I chose the '''us''' variant
** Host name, which will be the name of your computer, you can just press enter if you want to use the default
** Choose your network card, most people can just go with the default (press enter)
*** Most people will use DHCP, so press enter again, or you can enter in your static IP address
*** You will be asked if you want to do any manual network configuration, press enter for no
** Type in your root password
** Choose a time zone, you can get a list my pressing '''?'''. If you want a sub zone, e.g. Africa, type in Africa and press enter, '''?''' will give you a list of sub zones in Africa
** Press enter to choose the fastest mirror
*** Press enter again once a mirror has been chosen
** Choose a disk you want to install Alpine onto, as an example, I choose '''sda'''
*** Now choose how you would like to use it, for this guide, choose '''sys''', this will install the entire OS onto your hard drive
*** You are given a final chance to back out, type in '''Y''' to continue
* The installation is now complete and your be asked to reboot. Type in '''reboot''' and press enter
Take out the CD, and your computer should boot into Alpine using your hard drive.

=== Continue Setting up your Computer ===

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

Installing Alpine on HDD overwriting everything

2011-05-15T17:32:29Z

Bess: /* Installing Alpine to a new machine, overwriting everything on the harddisk */

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the Alpine ISO image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text '''login:''' to appear, type '''root''' and press enter.
* Run the '''setup-alpine''' script
** Choose your keyboard, as an example, I chose '''US'''
** Host name, which will be the name of your computer, you can just press enter if you want to use the default
** Choose your network card, most people can just go with the default (press enter)
*** Most people will use DHCP, so press enter again, or you can enter in your static IP address
** Type in your root password
** Choose a time zone, I chose '''NZ''' for New Zealand
** Press enter to choose the fastest mirror
*** Press enter again once a mirror has been chosen
** Choose a disk you want to install Alpine onto, if you only have one hard drive, then press enter
*** Now choose how you would like to use it, for this guide, choose '''sys''', this will install the entire OS onto your hard drive
*** You are given a final chance to back out, type in '''Y''' to continue
* The installation is now complete and your be asked to reboot. Type in '''reboot''' and press enter
Take out the CD, and your computer should boot into Alpine using your hard drive.

=== Continue Setting up your Computer ===

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

Installing Alpine on HDD overwriting everything

2011-05-09T16:54:11Z

Bess: Added in the Tutorials and Howtos Page

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the Alpine ISO image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text '''login:''' to appear, type '''root''' and press enter.
* Run the '''setup-alpine''' script
** Choose your keyboard, as an example, I chose '''US'''
** Host name, which will be the name of your computer, you can just press enter if you want to access the default
** Choose your network card, most people can just go with the default (press enter)
*** Most people will use DHCP, so press enter again, or you can enter in your static IP address
** Type in your root password
** Choose a time zone, I chose '''NZ''' for New Zealand
** Press enter to choose the fastest mirror
*** Press enter again once a mirror has been chosen
** Choose a disk you want to install Alpine onto, if you only have one hard drive, then press enter
*** Now choose how you would like to use it, for this guide, choose '''sys''', this will install the entire OS onto your hard drive
*** You are given a final chance to back out, type in "Y" to continue
* The installation is now complete and your be asked to reboot. Type in '''reboot''' and press enter
Take out the CD, and your computer should boot into Alpine using your hard drive.

=== Continue Setting up your Computer ===

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

Installing Alpine on HDD overwriting everything

2011-05-09T16:50:56Z

Bess: Major Change. This page only reflects the current install of Alpine. Added in a lot more detail.

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the Alpine ISO image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text '''login:''' to appear, type '''root''' and press enter.
* Run the '''setup-alpine''' script
** Choose your keyboard, as an example, I chose '''US'''
** Host name, which will be the name of your computer, you can just press enter if you want to access the default
** Choose your network card, most people can just go with the default (press enter)
*** Most people will use DHCP, so press enter again, or you can enter in your static IP address
** Type in your root password
** Choose a time zone, I chose '''NZ''' for New Zealand
** Press enter to choose the fastest mirror
*** Press enter again once a mirror has been chosen
** Choose a disk you want to install Alpine onto, if you only have one hard drive, then press enter
*** Now choose how you would like to use it, for this guide, choose '''sys''', this will install the entire OS onto your hard drive
*** You are given a final chance to back out, type in "Y" to continue
* The installation is now complete and your be asked to reboot. Type in '''reboot''' and press enter
Take out the CD, and your computer should boot into Alpine using your hard drive.

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Installing Alpine on HDD overwriting everything

2011-05-09T00:09:39Z

Bess:

{{Obsolete}}
Since version 2.2, the installer has changed a lot.
== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Update your repositories
{{Cmd|vi /etc/apk/repositories}}

http://dl-2.alpinelinux.org/alpine/v2.1/main
http://dl-3.alpinelinux.org/alpine/v2.1/main
http://dl-4.alpinelinux.org/alpine/v2.1/main
* Make sure the respository is working by typing in
{{Cmd|apk update}}
{{Note|The version needs to match the version you are installing, this is done so that the setup-disk command below can download fdisk if you are using the minimal install CD}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Installing Alpine on HDD overwriting everything

2011-03-02T20:24:54Z

Bess:

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Update your repositories
{{Cmd|vi /etc/repositories}}

http://dl-2.alpinelinux.org/alpine/v2.1/main
http://dl-3.alpinelinux.org/alpine/v2.1/main
http://dl-4.alpinelinux.org/alpine/v2.1/main
* Make sure the respository is working by typing in
{{Cmd|apk update}}
{{Note|The version needs to match the version you are installing, this is done so that the setup-disk command below can download fdisk if you are using the minimal install CD}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Installing Alpine on HDD overwriting everything

2011-03-02T18:59:13Z

Bess: corrected wiki tags

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Update your repositories
{{Cmd|vi /etc/repositories}}

http://dl-3.alpinelinux.org/alpine/v2.1/main
* Make sure the respository is working by typing in
{{Cmd|apk update}}
{{Note|The version needs to match the version you are installing, this is done so that the setup-disk command below can download fdisk if you are using the minimal install CD}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Alpine Package Keeper

2011-03-02T18:57:54Z

Bess: /* Update the Package list */ so that this matches by previous changes

= Alpine Linux Package Management =

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''

'''apk''' is the tool used to install, upgrade, or delete software on a running sytem<br />
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the apk tool - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

The '''apk''' tool has the following applets:

{|
| [[#Add a Package|add]]
| Add new packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Info on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache Maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|}

== Quickstart Guide ==

=== Packages and Repositories ===

Software packages for Alpine Linux are digitally signed tar.gz archives containing the programs, configuration files, and dependency metadata. They have the extension "*.apk", and are often called "a-packs"

The packages are stored in one or more ''repositories'' A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named APKINDEX.tar.gz to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in <tt>/etc/apk/repositories</tt>, one repository per line. If you booted from USB stick (<tt>/media/sda1</tt>) or CD-ROM (<tt>/media/cdrom</tt>), your repository file probably looks like this:

<pre>
/media/sda1/apks/
</pre>

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

<pre>
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.1/main
https://dl-3.alpinelinux.org/alpine/v2.1/main
ftp://dl-3.alpinelinux.org/alpine/v2.1/main
</pre>

{{note|Currently there are no public https or ftp repositories. The protocols are available for local repositories}}

=== Update the Package list ===

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the APKINDEX.tar.gz from each repository and stores it in the local cache, typically <tt>/var/lib/apk</tt> or <tt>/etc/apk/cache</tt>.

{{Cmd|apk update}}
<pre>
fetch http://dl-3.alpinelinux.org/alpine/v2.1/main/APKINDEX.tar.gz
</pre>

{{Tip|If using remote repositories, it is a good idea to do an '''update''' just before doing an '''add''' or '''upgrade''' command. That way you know you are using the latest software available}}

=== Add a Package ===

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{cmd|apk add openssh
apk add openssh openntp vim}}

=== Remove a Package ===

Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

=== Upgrade a Running System ===

To upgrade ''all'' the packages of a running system, use '''upgrade'''

{{cmd|apk update
apk upgrade
}}

To upgrade only a few packages, use the '''add''' command with the ''-u'' parameter:

{{cmd|apk update
apk add -u busybox
}}

{{Note|Remember that when you reboot your machine, the remote repository will not be available until after networking is started. This means packages newer than your local boot media will likely not be installed after a reboot. To make an "upgrade" persist over a reboot, use a [[#Local Cache|local cache]].}}

=== Search for Packages ===

The '''search''' command searches the repository Index files for installable packages.

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description: {{cmd|apk search -v -d 'NTP' }}

=== Info on Packages ===

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information); or all information is displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package
* The '''webpage''' where the application is hosted
* The '''size''' the package will require once installed (in bytes)
* What packages are required to use this one ('''depends''')
* What packages require this one to be installed ('''required by''')
* The '''contents''' of the package
* Any '''triggers''' this package sets. Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}
== Additional apk Commands ==

In progress...

== Local Cache ==

Alpine Linux needs to be able to pull packages from local media on boot. (You can't download packages from the net before you have a network connection.) Using remote repositories presents a problem. If the config files have been modified for a newer version of a package, and the older package is on local media, all sorts of fun can result.

The solution is a local cache of updated packages. This cache can be stored on any r/w media, typically the same location as the apkovl.

=== To Enable Local Cache ===

# Create a '''cache''' directory on the device you store your lbu backups (typically, <code>/dev/sda1</code>.) {{Cmd| mkdir /media/sda1/cache }}
# Create a symlink to this directory from <code>/etc/apk/cache</code>. {{Cmd|ln -s /media/sda1/cache /etc/apk/cache}}
# Run an lbu commit to save the change (<code>/etc/apk/cache</code> is in <code>/etc</code> and is automatically backed up.) {{Cmd|lbu commit}}
# Done. Now whenever you run an apk command that pulls a new package from a remote repository, The package is stored on your local media. On startup, Alpine Linux will check the local cache for new packages, and will install them in preference.

So you now have a run-from-RAM distro that can do a '''yum upgrade''' or '''apt-get dist-upgrade'''

=== Cache Maintenance ===

Over time, newer packages will replace older ones; the cache directory will contain all older versions of packages.

==== Delete Old Packages ====
To clean out older versions of packages, run the '''clean''' command. {{cmd|apk cache clean}} or to see what is deleted {{cmd|apk -v cache clean}}

==== Download Missing Packages ====
If you accidentally delete packages from the cache directory, you can make sure they are there with the '''download''' command, {{cmd|apk cache download}}

==== Delete and Download In One Step ====
You can combine the two steps into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|apk cache -v sync}}

==== Automatically Cleaning Cache on Reboot ====
To automatically attempt to validate your cache on reboot, you can add the above command to the <code>/etc/conf.d/local</code> script, in the <code>stop</code> stanza:

local_stop() {
# This is a good place to unload any misc.
# programs you started above.

# verify the local cache on shutdown
apk cache -v sync

# We should always return 0
return 0
}

{{Tip|Usually the only time you need to reboot is when things have gone horribly wrong; so this is a "best effort" to cover forgetting to sync the cache; It is much better to run '''sync''' immediately after adding or upgrading packages.}}

== Advanced APK Usage ==

=== Holding a specific package back ===

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

Alpine Package Keeper

2011-03-02T18:56:24Z

Bess: /* Packages and Repositories */ updated repositories to better reflect current usage

= Alpine Linux Package Management =

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''

'''apk''' is the tool used to install, upgrade, or delete software on a running sytem<br />
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the apk tool - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

The '''apk''' tool has the following applets:

{|
| [[#Add a Package|add]]
| Add new packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Info on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache Maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|}

== Quickstart Guide ==

=== Packages and Repositories ===

Software packages for Alpine Linux are digitally signed tar.gz archives containing the programs, configuration files, and dependency metadata. They have the extension "*.apk", and are often called "a-packs"

The packages are stored in one or more ''repositories'' A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named APKINDEX.tar.gz to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in <tt>/etc/apk/repositories</tt>, one repository per line. If you booted from USB stick (<tt>/media/sda1</tt>) or CD-ROM (<tt>/media/cdrom</tt>), your repository file probably looks like this:

<pre>
/media/sda1/apks/
</pre>

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

<pre>
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.1/main
https://dl-3.alpinelinux.org/alpine/v2.1/main
ftp://dl-3.alpinelinux.org/alpine/v2.1/main
</pre>

{{note|Currently there are no public https or ftp repositories. The protocols are available for local repositories}}

=== Update the Package list ===

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the APKINDEX.tar.gz from each repository and stores it in the local cache, typically <tt>/var/lib/apk</tt> or <tt>/etc/apk/cache</tt>.

{{Cmd|apk update}}
<pre>
fetch http://dl-3.alpinelinux.org/alpine/v1.10/packages/main/APKINDEX.tar.gz
fetch http://dl-3.alpinelinux.org/alpine/v1.10/packages/testing/APKINDEX.tar.gz
alpine 1.10.1 [/media/sda1/apks]
main v1.10.1-34-g977ff46 [http://dl-3.alpinelinux.org/alpine/v1.10/packages/main]
testing v1.10.0-32-gbf6b6cb [http://dl-3.alpinelinux.org/alpine/v1.10/packages/testing]
</pre>

{{Tip|If using remote repositories, it is a good idea to do an '''update''' just before doing an '''add''' or '''upgrade''' command. That way you know you are using the latest software available}}

=== Add a Package ===

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{cmd|apk add openssh
apk add openssh openntp vim}}

=== Remove a Package ===

Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

=== Upgrade a Running System ===

To upgrade ''all'' the packages of a running system, use '''upgrade'''

{{cmd|apk update
apk upgrade
}}

To upgrade only a few packages, use the '''add''' command with the ''-u'' parameter:

{{cmd|apk update
apk add -u busybox
}}

{{Note|Remember that when you reboot your machine, the remote repository will not be available until after networking is started. This means packages newer than your local boot media will likely not be installed after a reboot. To make an "upgrade" persist over a reboot, use a [[#Local Cache|local cache]].}}

=== Search for Packages ===

The '''search''' command searches the repository Index files for installable packages.

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description: {{cmd|apk search -v -d 'NTP' }}

=== Info on Packages ===

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information); or all information is displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package
* The '''webpage''' where the application is hosted
* The '''size''' the package will require once installed (in bytes)
* What packages are required to use this one ('''depends''')
* What packages require this one to be installed ('''required by''')
* The '''contents''' of the package
* Any '''triggers''' this package sets. Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}
== Additional apk Commands ==

In progress...

== Local Cache ==

Alpine Linux needs to be able to pull packages from local media on boot. (You can't download packages from the net before you have a network connection.) Using remote repositories presents a problem. If the config files have been modified for a newer version of a package, and the older package is on local media, all sorts of fun can result.

The solution is a local cache of updated packages. This cache can be stored on any r/w media, typically the same location as the apkovl.

=== To Enable Local Cache ===

# Create a '''cache''' directory on the device you store your lbu backups (typically, <code>/dev/sda1</code>.) {{Cmd| mkdir /media/sda1/cache }}
# Create a symlink to this directory from <code>/etc/apk/cache</code>. {{Cmd|ln -s /media/sda1/cache /etc/apk/cache}}
# Run an lbu commit to save the change (<code>/etc/apk/cache</code> is in <code>/etc</code> and is automatically backed up.) {{Cmd|lbu commit}}
# Done. Now whenever you run an apk command that pulls a new package from a remote repository, The package is stored on your local media. On startup, Alpine Linux will check the local cache for new packages, and will install them in preference.

So you now have a run-from-RAM distro that can do a '''yum upgrade''' or '''apt-get dist-upgrade'''

=== Cache Maintenance ===

Over time, newer packages will replace older ones; the cache directory will contain all older versions of packages.

==== Delete Old Packages ====
To clean out older versions of packages, run the '''clean''' command. {{cmd|apk cache clean}} or to see what is deleted {{cmd|apk -v cache clean}}

==== Download Missing Packages ====
If you accidentally delete packages from the cache directory, you can make sure they are there with the '''download''' command, {{cmd|apk cache download}}

==== Delete and Download In One Step ====
You can combine the two steps into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|apk cache -v sync}}

==== Automatically Cleaning Cache on Reboot ====
To automatically attempt to validate your cache on reboot, you can add the above command to the <code>/etc/conf.d/local</code> script, in the <code>stop</code> stanza:

local_stop() {
# This is a good place to unload any misc.
# programs you started above.

# verify the local cache on shutdown
apk cache -v sync

# We should always return 0
return 0
}

{{Tip|Usually the only time you need to reboot is when things have gone horribly wrong; so this is a "best effort" to cover forgetting to sync the cache; It is much better to run '''sync''' immediately after adding or upgrading packages.}}

== Advanced APK Usage ==

=== Holding a specific package back ===

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

Installing Alpine on HDD overwriting everything

2011-03-02T18:49:21Z

Bess: /* Installing Alpine to a new machine, overwriting everything on the harddisk */

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Update your repositories
vi /etc/repositories

http://dl-3.alpinelinux.org/alpine/v2.1/main
* Make sure the respository is working by typing in
apk update
{{Note|The version needs to match the version you are installing, this is done so that the setup-disk command below can download fdisk if you are using the minimal install CD}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Installing Alpine on HDD overwriting everything

2011-03-02T18:47:07Z

Bess: /* Installing Alpine to a new machine, overwriting everything on the harddisk */ added about updating your respositories

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Update your repositories
vi /etc/repositories
http://dl-3.alpinelinux.org/alpine/v2.1/main
{{Note|The version needs to match the version you are installing, this is done so that the setup-disk command below can download fdisk if you are using the minimal install CD}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''

Installing Alpine on HDD overwriting everything

2011-03-02T18:36:43Z

Bess: /* Installing Alpine to a new machine, overwriting everything on the harddisk */ password isn't required

== Installing Alpine to a new machine, ''overwriting everything on the harddisk'' ==

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

The following is meant to be an absolute newbie guide

* Burn the alpine iso image to a CD
* Put the CD into the new computer and turn on the power.
* Wait for the text "login:" to appear, type "root" and press enter.
* Run the "setup-alpine" script to choose your keyboard, network and password options.
{{Note|If you run setup-disk before setup-alpine, the setup-alpine script won't be available to you when you reboot.}}
* Type "setup-disk" and press enter.
* You will be asked where to install. If you don't understand the question, press y and enter.

The system is now installed and after a while you will see a message saying "Please reboot"

Type "reboot" and press enter. You can remove the CD now, since the system is installed. Your system is ready. You can have fries with that, although there are healthier alternatives.

{{Note|Since you are installing to harddisk, there is no need to use the [[Alpine local backup]] system}}

=== Continue Setting up your Computer ===

* [[Alpine Linux package management]] ''(How to add/remove packages on your Alpine)''
* [[Alpine boot services]] ''(Configure a service to automatically boot at next reboot)''
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''