Alpine Linux - User contributions [en]

Alpine Package Keeper

2017-10-11T21:11:28Z

Ttrask: Explain the repository and repositories-file commandline options

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.

= Overview =

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
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, 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 {{Path|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 {{Path|/etc/apk/repositories}}, one repository per line. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

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:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

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

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
http://nl.alpinelinux.org/alpine/v2.6/main
@edge http://nl.alpinelinux.org/alpine/edge/main
@testing http://nl.alpinelinux.org/alpine/edge/testing
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add stableapp newapp@edge bleedingapp@testing}}

Apk will now by default only use the untagged repositories, but adding a tag to specific package:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

== Commandline repository options ==

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:

{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

= 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 {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



{{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}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Add a local Package =

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

= 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'' or ''--upgrade'' option:

{{cmd|apk update
apk add --upgrade 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, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description '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 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 (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') 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
}}

== Listing installed packages ==

To list all installed packages, use:

<pre>apk info</pre>

To list all installed packages in alphabetical order, with a description of each, do:

<pre>apk -vv info|sort</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= 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'}}

[[Category:Package Manager]]

Alpine Linux:FAQ

2017-08-11T02:34:47Z

Ttrask: s/apt/apk/g

[[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?==
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 the 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}}

Ansible

2017-06-07T20:24:23Z

Ttrask: Replace command examples with use of actual ansible modules

[http://ansible.com/ ansible] is a simple configuration management, deployment, task-execution, and multinode orchestration framework. It uses SSH for the communication between the involved systems, no server or client daemons are needed, and no additional software beside Python on client boxes is required.

= Installation of ansible =
ansible is available in ''testing''. The latest package is broken, sorry.

{{Cmd|apk add ansible}}

== Create a SSH key ==
Generate a SSH key for the managed node. It's recommended to use a key which is protected with a password.

{{Cmd|ssh-keygen -t rsa}}

= Managed nodes =
There are only minimal requirements for the clients. For every system you want to manage, you need to have the client's SSH key in the <code>authorized_keys</code> file of the management system and Python.

Install the Python package.

{{Cmd|apk add python}}

== Transfer the SSH key ==
There are two ways to do it. From a default Alpine installation you can use ssh and cat to do it.

{{Cmd|<nowiki>ssh root@[IP of the management system] 'cat ~/.ssh/id_rsa.pub' | cat - >> ~/.ssh/authorized_keys</nowiki>}}

If you are planning to use additional features of SSH. <code>ssh-copy-id</code>, which is provided by the <code>openssh-client</code> package, can help you with the key setup.

{{Cmd|ssh-copy-id -i ~/.ssh/id_rsa.pub root@[IP of the management system]}}

= Setup hosts =
Add all your remote systems to <code>/etc/ansible/hosts</code>. For details, please refer to [http://ansible.cc/docs/patterns.html#hosts-and-groups Hosts and Groups] in the ansible documentation.

{{Cat|/etc/ansible/hosts|
192.168.1.50
10.0.0.12
webserver.example.org
mail.example.org}}

= First test =

{{Cmd|$ ansible all -m ping -u you --sudo}}

Another test is check all variables.

{{Cmd|# ansible [IP of your Alpine Linux box] -m setup}}

= Playbooks =
When writing playbooks for Alpine Linux there are modules to keep in mind:

<ol>
<li>There is support for OpenRC, the [[Alpine_Linux_Init_System|Init System]], in the service module.
<pre>
- service:
name: lighttpd
enabled: yes
state: started
</pre>
<li>There is support for [[Alpine_Linux_package_management|APK]] as of Ansible 2.0.
<pre>
- apk:
name: lighttpd
state: present
update_cache: yes
</pre>
<li>There is support for the [[Alpine_Wall|Awall]] firewall as of Ansible 2.4.
<pre>
- awall:
name: policyfile
state: enabled
activate: yes
</pre>
<li>If you are going to re-use playbooks from other Linux distribution, please keep in mind that Alpine Linux uses different paths for the binaries. <code>/bin/rm</code>
</ol>

The [http://git.alpinelinux.org/cgit/fab/alpine-ansible/ alpine-ansible git repository] contain some example playbooks.

[[Category:Installation]]

APKBUILD Reference

2016-10-19T18:18:59Z

Ttrask: Updates to install script descriptions

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented <code>like this</code>.

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, ''_luaversions'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should receive the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have <code>make DESTDIR="$pkgdir" install</code> in the ''package()'' function.
==== subpkgdir ====
: This directory should receive the files for a subpackage. This variable should only be used from subpackage functions.
==== builddir ====
: This variable should point to the directory inside the ''srcdir'' where the main package source is unpacked. This is typically ''$srcdir/$pkgname-$pkgver''. It’s used by the default ''prepare()'' function as a working directory when applying patches.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, armhf, aarch64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}

==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a group and a user to be created. For example:
<blockquote><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|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing <code>abuild checksum</code> and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== provides ====
: Add documentation.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one package to another, or when a package gets renamed.
==== replaces_priority ====
: The priority of the replaces. If multiple packages replace each other, then will the package with highest ''replaces_priority'' win.
==== 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 [[APKBUILD Reference#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).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful 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>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:* abuild currently supports the following archive types/archive file extensions:
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lzma
:** .tar.xz
:** .zip

:: {{Note|Legacy APKBUILD scripts define ''source'' variable as "saveas-[brain-dead-url]/[target-filename]" format instead of the modern [target-filename]::[brain-dead-url].<br />''BAD'': source="saveas-http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC/$pkgname-$pkgver.tar.gz"<br />''GOOD'': source=$pkgname-$pkgver.tar.gz::http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC"}}

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always execute after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. As example we could take open-vm-tools. Currently it contains the userspace tools and separate packages for the kernel modules (grsec and vserver). When we install the userspace tools, apk should automatically install the correct kernel modules and will need to figure out for which kernel. This is where install_if jumps in. For any of the kernel modules package we would use:

:<pre>install_if="linux-${_flavor}=${_kernelver} open-vm-tools"</pre>

:This will automatically install the package when the specified packages are installed or are in dependency tree.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: <code>return 0</code>
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: <code>mkdir -p "$pkgdir"</code>

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

[[Category:Development]]

Creating an Alpine package

2016-10-19T18:16:10Z

Ttrask: Updates to install script descriptions

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

== 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 create 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. If you point source to an tarball provided by a git web interface (gitweg, cgit, github), such as:
: <pre>http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</pre>
: You will run into issues because the checksum changes when downloading on the build system.

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



* abuild currently supports the following archive types/archive file extensions:
** .tar.gz / .tgz
** .tar.bz2
** .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 it the package INSTALL and README file (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. A good example is for instance "--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 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).

* [http://www.gentoo-portage.com Search ebuilds]
* [http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
* [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. Please use the short name and the release number in the license tag, e.g

{| cellpadding="5" border="1" class="wikitable"
|-
! Short name
! Full name
|-
| GPL2
| GNU General Public License Version 2.0
|-
| LGPL2+
| GNU Lesser General Public License Version 2.1
|-
| ASL 2.0
| Apache License Version 2.0
|-
| BSD
| BSD License
|-
| MIT
| MIT license
|-
| MPL 2.0
| Mozilla Public License v2.0
|-
| ZPL 2.0
| Zope Public License v 2.0
|-
| PHP
| PHP License v3.0
|-
| zlib
| zlib/libpng License
|-
|}

For the GNU General Public License the '+' means ''or (at your option) any later version.'' which covers future releases of that license. We skip the ''v'' because it's obvious that the number shows the version. If you are unsure about the short name of a license, please check the resources below for additional information.

* [https://wiki.archlinux.org/index.php/Licenses ArchLinux and Licensing]
* [https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses Fedora and Licensing]

If a package has a special/custom license 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.

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

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 higer 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 and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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. Way's 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 you are going to use multiple patches for a single package, the preferred way to handle those is a loop and numbering the patches.

for i in "$srcdir"/*.patch; do
msg "Applying ${i}"
patch -p0 -i $i || return 1
done

Because multiple patches can patch the same file, we could create offset for the next patch. To make sure we always patch in a specified way we should number the patches as followed:

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

This way we are always sure patch 1 is first and if we want to add additional patches between them we can use 11,12,21,22...

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

{{Tip|Common steps for building package contain ''./configure'', ''make'' and ''make install''. Everyone of them should be enclosed by ''|| return 1'' to check exit status. Otherwise even if previous step fails e.g. ''./configure'', next will be launched e.g. ''make''. This complicates identifying the point where the build breaks. The same applies to installing additional files.}}

==== 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 || return 1

To disable parallel we use:

make -j1 || return 1

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}}

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine 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 you 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}}

In the commit message, add the following (remove the comments in the last four lines):

{{Cmd| # Please enter the commit message for your changes
#[snip]
#
testing/$pkgname: new aport # this will be the subject line
# a blank line
$pkgurl # homepage of project
$pkgdesc # a one line description}}

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 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}}

== Send a patch ==

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

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

[[Category:Development]]

Freeswitch Voicemail On Alpine Linux

2016-09-08T20:15:58Z

Ttrask: Fix typo

= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items are not needed for Alpine Linux 3.2 or later. They are needed on earlier versions due to bad default paths in the Freeswitch package.}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to one of the Freeswitch default local extensions (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail,authenticator-plaintext" >> /etc/acf/acf.conf
Change the ACF voicemail domain to match the domain from the sample config. You should use the IP address of your voicemail server, as this is what the sample config uses.
sed -i /^domain=/d /etc/freeswitchvmail.conf
echo "domain=IPADDRESS" >> /etc/freeswitchvmail.conf

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the Freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The Freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused. Once again, to dial into Freeswitch you can use one of the Freeswitch default local extensions as explained above.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

= Other Features =
== Switching From wav to mp3 Recording (Recommended) ==
{{Note|The mp3 format is supported in acf-freeswitch-vmail-0.6.2 and later, available on Alpine Linux 3.2 or later.}}
By default, Freeswitch will store voicemail recordings in wav format. Freeswitch also has the option of storing the recordings in mp3 format if mod_shout is installed. As mp3 format requires less storage/bandwidth and enjoys better support by web browsers, I would recommend making this change:
=== 1. Add the mod_shout module ===
Modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_shout module
<load module="mod_shout"/>
=== 2. Change Record Format to mp3 ===
sed -i s/'name="file-extension" value="wav"'/'name="file-extension" value="mp3"'/ /etc/freeswitch/autoload_configs/voicemail.conf.xml
=== 3. Restart Freeswitch ===
/etc/init.d/freeswitch restart
== Using PostgreSQL ==
Freeswitch-1.2.5 and acf-freeswitch-vmail-0.5.0 fully support Postgresql as the voicemail database. These versions are available in Alpine Linux 3.2 and later. To configure it:
=== 1. Install Postgresql ===
apk add postgresql acf-postgresql
=== 2. Setup and Start Postgresql ===
rc-update add postgresql
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
=== 3. Create the Database ===
psql -U postgres -c "CREATE DATABASE voicemail"
=== 4. Stop Freeswitch ===
/etc/init.d/freeswitch stop
{{Note|Freeswitch does not always stop properly. You might need to run 'ps ax' to find the process and 'kill' it. Running '/etc/init.d/freeswitch zap' might also be necessary.}}
=== 5. Configure Freeswitch and acf-freeswitch-vmail ===
Edit /etc/freeswitch/autoload_configs/voicemail.conf.xml to set the odbc-dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
<param name="odbc-dsn" value="pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''" />
Edit /etc/freeswitchvmail.conf and set the dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
dsn=pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''
=== 6. Restart Freeswitch ===
/etc/init.d/freeswitch start

[[Category:ACF]]

SIP Provisioning On Alpine Linux

2016-08-10T20:41:35Z

Ttrask: Added more flesh

{{Draft}}
= Overview =
This page describes how to install a basic provisioning server for SIP devices based upon Postgresql and the ACF web interface. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4.

This solution is implemented by the acf-provisioning package. acf-provisioning is designed as a generic provisioning service which provides one web interface (ACF) to manage and configure devices and a second web interface to serve configuration files. The design is data-driven by database entries that define classes-of-service and parameters for each device. Configuration files are generated dynamically using the database parameter values and templates. Support for a variety of SIP clients is included by default.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install packages ==
Here are the basic packages for the provisioning functionality:
apk add acf-provisioning acf-postgresql acf-lighttpd
In addition, you can add firmware packages for the SIP devices you want to support (depending on the version of Alpine Linux, some packages may not be available or may be available from the community repository):
apk add acf-provisioning-cisco acf-provisioning-linksys acf-provisioning-polycom acf-provisioning-snom acf-provisioning-algo acf-provisioning-cyberdata
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM for storage. You can use the following command: apk fetch --quiet --stdout acf-provisioning-polycom | tar -C / -zvx}}

== 3. Configure Lighttpd ==
Lighttpd is used to provide the HTTP provisioning interface for the SIP devices. The provisioning package contains a sample configuration that can be used for lighttpd:
mv /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig
ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf
Modify mod_cgi.conf to treat CGI scripts as shell scripts, rather than perl:
sed -i 's~/usr/bin/perl"$~"~' /etc/lighttpd/mod_cgi.conf
Start the server:
/etc/init.d/lighttpd start

== 4. Start Postgresql ==
The device parameter details are stored in a Postgresql database. We can use the default configuration, so we just start the service:
/etc/init.d/postgresql start

== 5. Point your SIP device to the new server for provisioning ==
Instructions for various manufacturers are included on separate pages:
*[[SIP Provisioning With ACF - Algo]]
*[[SIP Provisioning With ACF - Cisco]]
*[[SIP Provisioning With ACF - CyberData]]
*[[SIP Provisioning With ACF - Linksys]]
*[[SIP Provisioning With ACF - Polycom]]
*[[SIP Provisioning With ACF - Snom]]

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).

== Create a Device ==
acf-provisioning is organized by device, not by SIP URI or extension. Thus, each physical or logical device, such as a phone or soft phone, should have its own device in the provisioning system.

If you have properly configured your SIP device to connect to the network and to the provisioning server, it will have already attempted to make contact with the provisioning server. If that is the case, you can create the device by finding the corresponding request and clicking on '''Create''':
''Applications: '''Provisioning''' > '''Requests''' > Device Request: '''Create'''
This will create a device with the proper device class and MAC address and redirect you to modify the device classes-of-service.

Otherwise, you can create a device from scratch using the ''Create'' tab:
''Applications: '''Provisioning''' > '''Create'''

Finally, there is an option on newer systems to create devices in bulk using the ''Bulk Create'' tab:
''Applications: '''Provisioning''' > '''Bulk Create'''

== Classes of Service ==
Provisioning Classes are used to define groups of parameters and parameter defaults to account for different device types and classes of service. The structure of classes, groups, and parameters are defined in the database, making it flexible and extensible. Class Groups define the different classes of service that may be configured for each device. The Classes define the options for each Class Group and which Parameter Groups would apply to each option. The Parameter Groups then define a group of parameters and corresponding defaults. Finally, the Parameters define all of the details of each parameter, such as type, label, description, global default, and validation.

By default, the system defines two Class Groups - Device Model and Services. The Device Model class group contains several Classes corresponding to a variety of supported SIP devices. Obviously, different device types would support different sets of parameters. The Services class group contains classes for Office/Residential/Public/Hotline Phones. These classes mostly are used to define different default values for features. The existing Class Groups, Classes, Parameter Groups, and Parameters can all be modified through the ACF web interface, or entirely new entries can be created, to customize the system.

[[Category:ACF]]

ACF mvc.lua example

2016-08-03T21:50:09Z

Ttrask: Add explanation of how the web app and acf-cli use the dispatch method with application-specific controllers

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an Alpine Linux box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes the form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.set_hostname, self.clientdata, "Update", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and set the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Hostname" })

-- Warning - io.popen has security risks, never pass user data to io.popen
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.value.hostname = cfe({ value=n, label="Hostname" })

return retval
end

-- Set the hostname from the value contained in the cfe created by get_hostname
mymodule.set_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be 16 characters or less"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is valid, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
-- Warning - io.popen has security risks, never pass user data to io.popen
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to set hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.set_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the action string passed to acf-cli is of the form "/prefix/controller/action". The prefix is the path within /etc/acf/app where the controller may be found, so "/test/" for our case. The controller is determined from the controller file name, so "hostname" for our case. And, the action corresponds to the function within the controller to call, so "edithostname" for our case. Also note that, in the two examples above, the first case reads the existing hostname and the second case updates it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is determined by the view.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions or model functions. Using the controller actions requires use of the clientdata structure to pass parameters. For calling the model functions, the application will call the get function to retrieve the form cfe, fill in the desired input values into the cfe, and then call the set function to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
==== test_dispatch ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=arg[1], viewtype=arg[2], submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()

Test the application. As can be seen in the code above, the first argument is the new hostname and the second is a viewtype.

alpine:~# chmod 755 test_dispatch
alpine:~# ./test_dispatch test
test:~# ./test_dispatch alpine
alpine:~#

Note that the application functions, but there is no output. This is because there is no viewtype supplied. There is built-in support for these standard viewtypes (not all apply): html, json, stream, serialized

alpine:~# ./test_dispatch test serialized
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Update"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"
test:~# ./test_dispatch alpine json
{"type":"form","label":"Edit Hostname","value":{"hostname":{"value":"alpine","type":"text","label":"Hostname"}},"option":"Update","descr":"Hostname Updated"}
alpine:~#

You can also use a custom viewtype and/or view to customize the output. This relies on haserl to parse the view file, and haserl lua functions are only available when launched from haserl scripts (it would be nice if haserl were available as a standalone lua library). Haserl scripts expect to be launched by a web browser to handle CGI data, so passing input is trickier. I'm sure there is a better way to do this, but this is just an example:

==== test_haserl ====
#!/usr/bin/haserl-lua5.2 --shell=lua
<%
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=FORM.hostname, viewtype=FORM.viewtype, submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()
%>

==== /etc/acf/app/test/hostname-edithostname-text.lsp ====
<%
local data, viewlibrary, page_info, session = ...

if data.errtxt then
print(data:print_errtxt())
else
print(data.descr)
end
%>

Test the application

test:~# chmod 755 test_haserl
test:~# QUERY_STRING='hostname=alpine&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Hostname Updated
alpine:~# QUERY_STRING='hostname=asdfasdfasdfasdfasdf&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

You can further customize the application by creating your own application-specific controller. This is how the web interface and the acf-cli application are written. In both cases, a simple application is written to load not just an mvc:new() reference, but an application-specific controller to wrap the mvc:new() object. The dispatch function is then called on the application-specific controller object, which can override any function in mvc.lua to add a customized implementation. For example, both applications override the handle_clientdata function to customize the way input data is provided in the clientdata structure, and the web interface-specific controller contains a lot of code to handle features such as menus, templates, skins, authentication, redirection, ... The best way to understand this is to just read the code.

* Web application
** Application - [http://git.alpinelinux.org/cgit/acf/acf-core/tree/www/cgi-bin/acf acf]
** Controller - [http://git.alpinelinux.org/cgit/acf/acf-core/tree/app/acf_www-controller.lua acf_www-controller.lua]
* acf-cli
** Application - [http://git.alpinelinux.org/cgit/acf/acf-core/tree/bin/acf-cli acf-cli]
** Controller - [http://git.alpinelinux.org/cgit/acf/acf-core/tree/app/acf_cli-controller.lua acf_cli-controller.lua]

=== Use the New method ===
==== test_new ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- load the hostname controller
HOSTNAME=MVC:new("/test/hostname")

local hostname

-- METHOD 1 - controller action
HOSTNAME.clientdata = {hostname=arg[1], submit="Update"}
hostname = HOSTNAME:edithostname()

-- METHOD 2 - model functions
hostname = HOSTNAME.model:get_hostname()
hostname.value.hostname.value = arg[1]
hostname = HOSTNAME.model:set_hostname(hostname)

if hostname.errtxt then
print(hostname:print_errtxt())
else
print(hostname.descr or "Hostname Updated")
end

HOSTNAME:destroy()
MVC:destroy()

Once you have a hostname controller object, you can access its actions, passing data through clientdata, or you can directly access the get/set functions of the model. Test the app:

test:~# chmod 755 test_new
test:~# ./test_new alpine
Hostname Updated
alpine:~# ./test_new asdfasdfasdfasdfasdf
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

{{Obsolete}}

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ISP Mail Server 3.x HowTo

2016-07-26T23:50:06Z

Ttrask: Add ACF category

{{Draft|This is a work in progress based on migrating alpinelinux mail servers to 3.x}}

== A Full Service Mail Server ==

This document describes installation process for the Alpine Linux 3.x platform. The goal of this document is to describe how to set up postfix, dovecot, clamav, dspam, roundecube, and postfixadmin for a full-featured "ISP" level mail server. This document superceeds the previous [[ISP Mail Server 2.x HowTo]] instructions for Alpine 2.x. For this guide, we start with a server ''without'' ACF installed.

The server provides:

* multiple virtual domains
* admins for each domain (to add/remove virtual accounts)
* quota support per domain / account
* downloading email via IMAP / IMAPS / POP3 / POP3S
* relaying email for authenticated users with TLS or SSL (Submission / SMTPS protocol)
* standard filters (virus/spam/rbl/etc)
* web mail client
* value add services

== Set up Lighttpd + PHP ==

PostfixAdmin needs php pgpsql and imap modules, so we do it in this step.

apk add lighttpd php php-cgi php-pgsql php-imap

We are setting this up to be a multi-domain virtual web server (replace host.example.com with the actual domain):
<nowiki>mkdir -p /var/www/domains/host.example.com/www
cat <<-EOF >/var/www/domains/host.example.com/www/index.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>host.example.com Redirector</title>
</head>
<body>
<ul>
<li><a href="/postfixadmin">PostfixAdmin</a></li>
<li><a href="/roundcube">Roundcube</a></li>
</ul>
</body>
EOF
</nowiki>

Get a web certificate, and install it. There are several options:
# Use a self-signed certificate, such as [[Generating SSL certs with ACF]]
# Use the certificate created with '''setup-acf''', if you installed ACF
# Get a certificate from a trusted root Certificate Authority, such as StartSSL.com, Thawte.com, Verisign.com, etc.

These instructions will use a certificate issued from a self-signed ACF based CA

openssl pkcs12 -nokeys -cacerts -in certificate.pfx -out /etc/lighttpd/ca-crt.pem
openssl pkcs12 -nodes -in certificate.pfx -out /etc/lighttpd/server-bundle.pem
chown root:root /etc/lighttpd/server-bundle.pem
chmod 400 /etc/lighttpd/server-bundle.pem

'''Note:''' The server certificate ''and'' key are in the server-bundle.pem file, so it is critical that the file be read-only by user "root".

Add these lines to /etc/lighttpd/lighttpd.conf to point to the new document root, and set it up to listen on port 443 (replace ''host.example.com'' with the actual domain and ''ip_address_of_server'' with the actual IP address):

<pre>

simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/host.example.com/"
simple-vhost.document-root = "www/"

$SERVER["socket"] == "ip_address_of_server:443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server-bundle.pem"
ssl.ca-file = "/etc/lighttpd/ca-crt.pem"
}
</pre>

Ensure that the simple_vhosts module is loaded, as well as the cgi config scripts by uncommenting the following lines in /etc/lighttpd/lighttpd.conf:

server.modules = (
# other modules may be listed
"mod_simple_vhost",
# other modules may be listed
.
.
.
include "mod_fastcgi.conf"

start lighttpd, test:

rc-update add lighttpd
rc

At this point you should be able to see the redirect page: https://host.example.com/

== Install Postgresql ==

Add and configure postgresql:

apk add postgresql postgresql-client
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
rc-update add postgresql

At this point any user can connect to the sql server with "trust" mechanism. If you want to enforce password authentication (you probably do) edit /var/lib/postgresql/9.0/data/pg_hba.conf. Since by default "trust" mechanism is for local connections only we assume using trust password-less access as safe.

Create the postfix database:

psql -U postgres
create user postfix with password '******';
create database postfix owner postfix;
\q

(Of course, use your selected password where ******* is shown above.)

== Install PostfixAdmin ==

We are going to install the postfix admin web front-end before we install the mail server. This just creates an interface to populate the SQL tables that postfix and dovecot will use.

Download PostfixAdmin from Sourceforge. When these instructions were written, 2.92 was the current release, so (replace host.example.com with the actual domain):

wget http://downloads.sourceforge.net/project/postfixadmin/postfixadmin/postfixadmin-2.92/postfixadmin-2.92.tar.gz
tar zxvf postfixadmin-2.92.tar.gz
mkdir -p /var/www/domains/host.example.com/www/postfixadmin
mv postfixadmin-2.3.3/* /var/www/domains/host.example.com/www/postfixadmin
rm -rf postfixadmin*

Edit /var/www/domains/host.example.com/www/postfixadmin/config.inc.php and modify at least these lines (replace host.example.com with the actual domain):

$CONF['configured'] = true;
$CONF['setup_password'] = ""; << Don't change this yet
$CONF['database_type'] = 'pgsql';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfix';
$CONF['database_password'] = '*****'; << The password you chose above
$CONF['database_name'] = 'postfix';
$CONF['database_prefix'] = "";
$CONF['admin_email'] = 'you@some.email.com'; << Your email address
$CONF['encrypt'] = 'md5crypt';
$CONF['authlib_default_flavor'] = 'md5raw';
$CONF['dovecotpw'] = "/usr/sbin/dovecotpw";
$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
$CONF['aliases'] = '10';
$CONF['mailboxes'] = '10';
$CONF['maxquota'] = '10';
$CONF['quota'] = 'YES';
$CONF['quota_multiplier'] = '1024000';
$CONF['vacation'] = 'NO';
$CONF['vacation_control'] ='NO';
$CONF['vacation_control_admin'] = 'NO';
$CONF['alias_control'] = 'YES';
$CONF['alias_control_admin'] = 'YES';
$CONF['special_alias_control'] = 'YES';
$CONF['fetchmail'] = 'NO';
$CONF['user_footer_link'] = "http://host.example.com/postfixadmin";
$CONF['footer_link'] = 'http://host.example.com/postfixadmin/main.php';
$CONF['create_mailbox_subdirs_prefix']="";
$CONF['used_quotas'] = 'YES';
$CONF['new_quota_table'] = 'YES';

You should further edit /var/www/domains/host.example.com/www/postfixadmin/config.inc.php and replace all instances of "change-this-to-your.domain.tld" with your actual mail domain. This can be done with busybox sed (replace example.com with your domain name):

sed -i -e 's/change-this-to-your.domain.tld/example.com/g' /var/www/domains/host.example.com/www/postfixadmin/config.inc.php

Go to https://host.example.com/postfixadmin/setup.php

Create the password hash, add it to the config.inc.php file

Go back to https://host.example.com/postfixadmin/setup.php

Create superadmin account.

'''NOTE:''' Check http://sourceforge.net/tracker/index.php?func=detail&aid=2859165&group_id=191583&atid=937964 if you have bug on listing domains page.

== Install Postfix ==

Create a user for the virtual mail delivery, and get its uid/gid (you'll need the numeric uid/gid for postfix):

adduser vmail -H -D -s /bin/false
grep vmail /etc/passwd

(In examples below, we use 1006/1006 for the uid/gid)

Create the mail directory, and assign vmail as the owner:

mkdir -p /var/mail/domains
chown -R vmail:vmail /var/mail/domains

Install postfix:

apk add postfix postfix-pgsql postfix-pcre

Edit the /etc/postfix/main.cf file. Here's an example (don't forget to replace the uid/gid):

myhostname=host.example.com
mydomain=example.com

mydestination = localhost.$mydomain, localhost
mynetworks_style = subnet
mynetworks = 127.0.0.0/8

virtual_mailbox_domains = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_domains_maps.cf
virtual_alias_maps = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_catchall_maps.cf

virtual_mailbox_maps = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_mailbox_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_mailbox_maps.cf

virtual_mailbox_base = /var/mail/domains/
virtual_gid_maps = static:1006
virtual_uid_maps = static:1006
virtual_minimum_uid = 100
virtual_transport = virtual

# This next command means you must create a virtual
# domain for the host itself - ALL mail goes through
# The virtual transport

mailbox_transport = virtual
local_transport = virtual
local_transport_maps = $virtual_mailbox_maps

smtpd_helo_required = yes
disable_vrfy_command = yes
message_size_limit = 10240000
queue_minfree = 51200000

smtpd_sender_restrictions =
permit_mynetworks,
reject_non_fqdn_sender,
reject_unknown_sender_domain

smtpd_recipient_restrictions =
reject_non_fqdn_recipient,
reject_unknown_recipient_domain,
permit_mynetworks,
permit_sasl_authenticated,
reject_unauth_destination,
reject_rbl_client dnsbl.sorbs.net,
reject_rbl_client zen.spamhaus.org,
reject_rbl_client bl.spamcop.net

smtpd_data_restrictions = reject_unauth_pipelining

# we will use this later - This prevents cleartext authentication
# for relaying
smtpd_tls_auth_only = yes

# Silence the EAI warning on alpine linux
smtputf8_enable = no

Now we need to create a *bunch* of files so that postfix can get the delivery information out of sql. Here's a shell script to create the scripts. Change PGPW to the password for the postfix user of the postfix SQL database:

cd /etc/postfix
mkdir sql
PGPW="ChangeMe"

cat - <<EOF >sql/pgsql_virtual_alias_domain_catchall_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select goto From alias,alias_domain where alias_domain.alias_domain = '%d' and alias.address = '@' || alias_domain.target_domain and alias.active = true and alias_domain.active= true
EOF

cat - <<EOF >sql/pgsql_virtual_alias_domain_mailbox_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select maildir from mailbox,alias_domain where alias_domain.alias_domain = '%d' and mailbox.username = '%u' || '@' || alias_domain.target_domain and mailbox.active = true and alias_domain.active
EOF

cat - <<EOF >sql/pgsql_virtual_alias_domain_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = select goto from alias,alias_domain where alias_domain.alias_domain='%d' and alias.address = '%u' || '@' || alias_domain.target_domain and alias.active= true and alias_domain.active= true
EOF

cat - <<EOF >sql/pgsql_virtual_alias_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select goto From alias Where address='%s' and active ='1'
EOF

cat - <<EOF >sql/pgsql_virtual_domains_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select domain from domain where domain='%s' and active='1'
EOF

cat - <<EOF >sql/pgsql_virtual_mailbox_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select maildir from mailbox where username='%s' and active=true
EOF

chown -R postfix:postfix sql
chmod 640 sql/*

At this point you should be able to start up postfix:

newaliases # so postfix is happy...
/etc/init.d/postfix start
rc-update add postfix

=== Create a domain in PostfixAdmin and test ===

Go to http://host.example.com/postfixadmin/

Log in using the superadmin account, create a domain for the local box (e.g. example.com), and create a user mailbox (e.g. root).

From the machine, send a test message:

sendmail -t root@example.com
subject: test
.
^d

In /var/log/mail.log (or /var/log/messages, if you still have busybox syslogd running) you should see the message queued. The message should be in /var/mail/domains/example.com/root/new

== Install Dovecot ==

Dovecot is the POP3/IMAP server to retrieve mail.

Install dovecot:

apk add dovecot dovecot-pgsql

Edit /etc/dovecot/dovecot.conf:

<pre>
auth_mechanisms = plain login
auth_username_format = %Lu
#auth_verbose = yes
#auth_debug = yes
#auth_debug_passwords = no

disable_plaintext_auth = no

mail_location = maildir:/var/mail/domains/%d/%n

first_valid_gid = 1000
first_valid_uid = 1000
last_valid_gid = 65535
last_valid_uid = 65535

log_timestamp = "%Y-%m-%d %H:%M:%S "
login_greeting = IMAP server ready

protocols = imap

service anvil {
client_limit = 2100
}

ssl_cert = /etc/lighttpd/server-bundle.pem
ssl_key = /etc/lighttpd/server-bundle.pem

userdb {
args = uid=1006 gid=1006 home=/var/mail/domains/%d/%n
driver = static
}

passdb {
args = /etc/dovecot/dovecot-sql.conf
driver = sql

namespace inbox {
inbox = yes

mailbox Trash {
auto = create
special_use = \Trash
}

mailbox Spam {
auto = no
special_use = \Junk
}

mailbox Sent {
auto = subscribe
special_use = \Sent
}
}
</pre>

Be sure to replace the uid and gid with the appropriate values for the vmail user.

We need a certificate for SSL/TLS authentication, so in the example above, we use the lighttpd cert. That way when the cert is renewed/replaced, Dovecot will have access to the new cert as well.

Create the /etc/dovecot/dovecot-sql.conf file:

driver = pgsql
connect = host=localhost dbname=postfix user=postfix password=********
password_query = select username,password from mailbox where local_part = '%n' and domain = '%d'
default_pass_scheme = MD5-CRYPT

Again, change the password above to your postfix user password, and protect the file from prying eyes:

chown root:root /etc/dovecot/dovecot-sql.conf
chmod 600 /etc/dovecot/dovecot-sql.conf

Start dovecot
/etc/init.d/dovecot start
rc-update add dovecot

== Testing ==

Make sure your firewall allows in ports 25(SMTP) 110 (POP3), 995 (POP3S), 143(IMAP), 993(IMAPS), or whatever subset you support.

At this point, you should be able to:
* Create a new domain and add users with PostfixAdmin
* Send mail to those users via SMTP to port 25
* Retrieve mail using the user's full email and password (e.g. username: user@example.com password: ChangeMe)

== Value Add Features ==

If you followed the guide above, you now have a functional mail server with many interconnected parts. The features below assume that the server is already running as described above. You should be able to add any or all of these features below to further enhance the mail service.

=== Virus Scanning ===

This procedure uses clamav and the postfix content_filter mechanism to scan inbound and outbound email for viruses. Infected emails are dropped. Clean emails are tagged with a "scanned by clamav" header.

* Install clamav and clamsmtp:
apk add acf-clamav clamsmtp
* Edit the /etc/clamav/clamd.conf file if desired (not necessary in most cases)
* Edit /etc/clamsmtpd.conf and verify the following lines
OutAddress: 10026
Listen: 127.0.0.1:10025
Header: X-Virus-Scanned: ClamAV using ClamSMTP
Action: drop
User: clamav
* Start the daemons
rc-update add clamd
rc-update add clamsmtpd
/etc/init.d/clamd start
/etc/init.d/clamsmtpd start
* Verify clamsmtp is listening on port 10025:
netstat -anp | grep clamsmtp
* [http://memberwebs.com/stef/software/clamsmtp/postfix.html Following the clamsmtp instructions]
** edit /etc/postfix/main.cf and add:
content_filter = scan:[127.0.0.1]:10025
** edit /etc/postfix/master.cf and add
# AV scan filter (used by content_filter)
scan unix - - n - 16 smtp
-o smtp_send_xforward_command=yes
-o smtp_enforce_tls=no
# For injecting mail back into postfix from the filter
127.0.0.1:10026 inet n - n - 16 smtpd
-o content_filter=
-o receive_override_options=no_unknown_recipient_checks,no_header_body_checks
-o smtpd_helo_restrictions=
-o smtpd_client_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks_style=host
-o smtpd_authorized_xforward_hosts=127.0.0.0/8
* postfix reload
* Send and email into a local virtual domain - it should have the ''X-Virus-Scanned: ClamAV using ClamSMTP'' header.

=== Relay for Authenticated Users ===

As configured above, the mail server accepts email from the Internet, but it does not relay email. If it is a perimeter exchanger for a protected network, then you can add the protected networks to the ''mynetworks'' configuration line in /etc/postfix/main.cf

This configuration change allows ''remote'' users to authenticate against the mail server and relay through it. The rules for relaying are:
* Only authenticated users can relay
* Authentication Credentials must be encrypted with TLS or SSL
* Allow Submission and SMTPS ports for relaying (many consumer networks block port 25 - SMTP by default)
The process uses the dovecot authentication mechanism (used with IMAPS) to authenticate users before they are allowed to relay through postfix.

* Edit /etc/dovecot/dovecot.conf and add the following:
# this is for postfix SASL (authenticated users can relay through us)

service auth {
unix_listener /var/spool/postfix/private/auth {
group = postfix
mode = 0660
user = postfix
}
unix_listener /var/spool/postfix/auth-master {
group = postfix
mode = 0660
user = vmail
}
user = root
}

* Restart dovecot
/etc/init.d/dovecot restart
* Edit /etc/postfix/main.cf and add:
# TLS Stuff -- since we allow SASL with tls *only*, we have to set up TLS first

smtpd_tls_cert_file = /etc/lighttpd/server-bundle.pem
smtpd_tls_key_file = /etc/lighttpd/server-bundle.pem
smtpd_tls_CAfile = /etc/lighttpd/ca-crt.pem
# If tls_security_level is set to "encrypt", then SMTP rejects
# unencrypted email (e.g. normal mail) which is bad.
# By setting it to "may" you get TLS encrypted mail from google, slashdot, and other
# interesting places. Check your logs to see who
smtpd_tls_security_level = may
# Log info about the negotiated encryption levels
smtpd_tls_received_header = yes
smtpd_tls_loglevel = 1

# SASL - this allows senders to authenticiate themselves
# This along with "permit_sasl_authenticated" in smtpd_recipient_restrictions allows relaying
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
smtpd_sasl_authenticated_header = yes
broken_sasl_auth_clients = yes
smtpd_tls_auth_only = yes
* Edit /etc/postfix/master.cf and enable the submission and smtps transports. They are probably already at the top of your master.cf file, just commented out:
submission inet n - n - - smtpd
-o smtpd_tls_security_level=encrypt
-o smtpd_sasl_auth_enable=yes
-o smtpd_client_restrictions=permit_sasl_authenticated,reject
-o milter_macro_daemon_name=ORIGINATING
smtps inet n - n - - smtpd
-o smtpd_tls_security_level=encrypt
-o smtpd_tls_wrappermode=yes
-o smtpd_sasl_auth_enable=yes
-o smtpd_client_restrictions=permit_sasl_authenticated,reject
-o milter_macro_daemon_name=ORIGINATING
*Verfiy submission and smtps are defined in /etc/services
grep "submission\|ssmtp" /etc/services
submission 587/tcp # mail message submission
submission 587/udp
smtps 465/tcp ssmtp # smtp protocol over TLS/SSL
smtps 465/udp ssmtp
* Restart postfix
postfix reload

At this point, you should be able to set up a mail client to relay through the server with TLS (port 587) or SSL (port 465) Note that "plain" authentication is used because the underlying link is encrypted. For example, in Thunderbird leave "secure authentication" unchecked, and choose STARTTLS (or TLS) for the connection security.

=== Mailbox Quotas ===

In the default configuration, PostfixAdmin knows about quotas, but they are not enforced. Documentation on the web mentions the [http://vda.sourceforge.net vda patch to postfix] to enforce quotas. The only bad thing... its a ''patch''. Postfix and Dovecot are both conservative systems, so if the patch isn't in the upstream source, we'll assume there's a good reason. There is a way of using quotas without patches - and it involves using dovecot's [http://wiki2.dovecot.org/LDA deliver] lda for local delivery.

* Replace /etc/dovecot/dovecot.conf with the following:

<pre>
auth_mechanisms = plain login
auth_username_format = %Lu
#auth_verbose = yes
#auth_debug = yes
#auth_debug_passwords = no

disable_plaintext_auth = no

info_log_path = /var/log/dovecot-info.log
log_path = /var/log/dovecot.log

mail_location = maildir:/var/mail/domains/%d/%n

first_valid_gid = 1000
first_valid_uid = 1000
last_valid_gid = 65535
last_valid_uid = 65535

log_timestamp = "%Y-%m-%d %H:%M:%S "
login_greeting = IMAP server ready

protocols = imap

service anvil {
client_limit = 2100
}

service auth {
unix_listener /var/spool/postfix/auth-master {
group = postfix
mode = 0660
user = vmail
}
unix_listener /var/spool/postfix/private/auth {
group = postfix
mode = 0660
user = postfix
}
user = root
}

service imap-login {
inet_listener imap {
address = 127.0.0.1
port = 143
}
inet_listener imaps {
address = *
port = 993
}
process_limit = 1024
}

service pop3-login {
process_limit = 1024
}

service dict {
unix_listener dict {
group =
mode = 0600
user = vmail
}
}

ssl_ca = </etc/ssl/certs/<CA Certificate file>
ssl_cert = </etc/ssl/private/<Public part of certificate file>
ssl_key = </etc/ssl/private/<Private part of certificate file>

passdb {
args = /etc/dovecot/dovecot-pgsql.conf
driver = sql
}

userdb {
driver = prefetch
}

userdb {
args = /etc/dovecot/dovecot-pgsql.conf
driver = sql
}

plugin {
quota = dict:user::proxy::quotadict

autocreate = Trash
autocreate2 = Spam
autocreate3 = Sent
autosubscribe = Trash
autosubscribe2 = Spam
autosubscribe3 = Sent
}

protocol imap {
mail_plugins = autocreate quota imap_quota
}

protocol pop3 {
mail_plugins = quota
}

dict {
quotadict = pgsql:/etc/dovecot/dovecot-dict-quota.conf
}

protocol lda {
auth_socket_path = /var/spool/postfix/auth-master
mail_plugins = quota
postmaster_address = postmaster@host.example.com
sendmail_path = /usr/sbin/sendmail
}
</pre>

* edit <tt>/etc/dovecot/dovecot-sql.conf</tt> and replace the user and password queries with the following (you may not have a user_query yet - add it):

password_query = select username as user, password, 1006 as userdb_uid, 1006 as userdb_gid, '*:bytes=' || quota as userdb_quota_rule from mailbox where local_part = '%n' and domain = '%d'
user_query = select '/var/mail/domains/' || maildir as home, 1006 as uid, 1006 as gid, '*:bytes=' || quota as quota_rule from mailbox where local_part = '%n' and domain ='%d'

* create <tt>/etc/dovecot/dovecot-dict-quota.conf</tt>
connect = host=localhost dbname=postfix user=postfix password=********

map {
pattern = priv/quota/storage
table = quota2
username_field =username
value_field = bytes
}

map {
pattern= priv/quota/messages
table = quota2
username_field = username
value_field = messages
}

Again, change the password above to your postfix user password, and protect the file from prying eyes:
chown dovecot:root /etc/dovecot/dovecot-sql.conf
chmod 600 /etc/dovecot/dovecot-sql.conf
chown dovecot:root /etc/dovecot/dovecot-dict-quota.conf
chmod 600 /etc/dovecot/dovecot-dict-quota.conf

Side note: [http://wiki2.dovecot.org/Quota/Dict The Dovecot Quota Documentation] mentions the need for a trigger with pgsql. This was created in the PostfixAdmin install, which is why you instantiated the pgsql language when creating the database. If not, you will need to create the trigger, to reference the quota2 table, not the quota table mentioned in the dovecot docs.

* create a new transport for the dovecot lda. Add the following to /etc/postfix/master.cf:
# The dovecot deliver lda
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/libexec/dovecot/deliver -f ${sender} -d ${user}@${nexthop}

* Edit the /etc/postfix/main.cf. Replace
virtual_transport = virtual
with
virtual_transport = dovecot
dovecot_destination_recipient_limit = 1

Change permissions on the /var/log/dovecot* log files, so that the vmail user can write to them:

chown vmail:vmail /var/log/dovecot*

Restart Postfix and Dovecot:

/etc/init.d/postfix restart
/etc/init.d/dovecot restart

'''TODO''' This will cause over-quota emails to bounce. Which could be a source of backscatter. We need a way of checking quota limits after RBL checking but before the message is accepted in the queue.

=== WebMail (RoundCube) ===

[http://roundcube.net/ RoundCube] is an "ajax /Web2.0" web-mail client. These instructions are for the Alpine Linux 2.2 repository

* Verify that you have at least the following in /etc/postfix/main.cf. Unless you have followed the Relay for Authenticated Users section above, set '''smtpd_tls_auth_only = no''', otherwise leave it set to '''yes''':

<pre>
# SASL - this allows senders to authenticiate themselves
# This along with "permit_sasl_authenticated" in smtpd_recipient_restrictions allows relaying
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
smtpd_sasl_authenticated_header = yes
# Set the next line to no if TLS auth is not configured
smtpd_tls_auth_only = no
</pre>

* Ensure you have followed section ''Relay_for_Authenticated_Users''.

* Restart the relevant services:

<pre>
/etc/init.d/postfix restart
/etc/init.d/dovecot restart
</pre>

* Add the package and related php modules:

apk add roundcubemail php-xml php-openssl php-mcrypt php-gd php-iconv php-dom php-intl php-pdo php-ldap php-pdo_pgsql php-zlib

* Link the roundcube application back into the docroot

ln -s /usr/share/webapps/roundcube /var/www/domains/host.example.com/www/roundcube

* Install ''roundcubemail-install'' package

apk add roundcubemail-installer

* Follow the instructions in /usr/share/webapps/roundcube/INSTALL:
cd /usr/share/webapps/roundcube
chown -R lighttpd:lighttpd /var/log/roundcube

su postgres
createuser roundcube
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) y
createdb -O roundcube -E UNICODE -T template0 roundcubemail
psql roundcubemail
roundcubemail=# ALTER USER roundcube WITH PASSWORD 'the_new_password';
roundcubemail=# \c - roundcube
roundcubemail=> \i /usr/share/webapps/roundcube/SQL/postgres.initial.sql
roundcubemail=> \q
exit

* Edit /etc/php/php.ini and set date.timezone to your local timezone, or to UTC

* Restart lighttpd to verify the new php libraries are used

/etc/init.d/lighttpd restart

* Get the additional php modules needed:
apk add curl php-phar git
cd /usr/share/webapps/roundcube
curl -sS https://getcomposer.org/installer | php
cp composer.json-dist composer.json
# Note - As of 11 Aug 2015, with Roundcube 1.1.2, there is a regression that is
# fixed here: https://github.com/roundcube/roundcubemail/commit/b3e9764c311a39012de1fa8ffd0fe874fbb322ef
# Update your composer.json accordingly:
# - "pear/mail_mime": ">=1.9.0",
# - "pear/net_smtp": "dev-master"
# + "pear-pear.php.net/mail_mime": ">=1.9.0",
# + "pear-pear.php.net/net_smtp": ">=1.6.3"
php composer.phar install --no-dev

* Point your browser to https://host.example.com/roundcube/installer
* Start installation

For the specific configuration parameters in the install step:

{| class="wikitable"
!Property
!Setting
|-
| ''enable_spellcheck'' || disabled
|-
| ''identities_level'' || one identity with possibility to edit all params but not email address
|-
| ''log driver'' || syslog
|-
| ''sylog_id'' || roundcube
|-
| ''syslog_facility'' || mailsubsystem
|-
| ''db_dnsw'' || pgsql properties, as described above
|-
| ''imap_host'' || 127.0.0.1
|-
| ''default port'' || 143
|-
| ''auto_create_user'' || enabled
|-
| ''smtp_server'' || 127.0.0.1
|-
| ''smtp_port'' || 25
|-
| ''smtp_user/smtp_pass'' || enable ''Use Current IMAP username and password for SMTP authentication''
|-
| ''smtp_log'' || enable (optional, but gives additional log record)
|}

The other items can be left at default settings, or adjusted if desired.

* Follow the instructions in step 2 of the install to copy the files to the server
* You should now be able to get to roundcube at https://host.example.com/roundcube

* After its working, the INSTALL file recommends removing the install directory.

apk del roundcubemail-installer

* Disable installer mode in /etc/roundcube/main.inc.php file:

$rcmail_config['enable_installer'] = false;

* Change the ownership and permissions

cd /usr/share/webapps/roundcube
chown -R root:root LICENSE UPGRADING INSTALL README CHANGELOG
chmod -R 600 LICENSE UPGRADING INSTALL README CHANGELOG

* If needed customize logos such as '''watermark.gif''', '''roundcube_logo.gif''', '''favicon.ico'''

* If you would like to disable displaying of standard logos update template files accordingly

* Comment all entries like '''<div ... img src="/images/roundcube_logo.png"...''' in files:

includes/header.html
templates/error.html
templates/messageprint.html
templates/login.html
templates/printmessage.html

* Comment all entries like '''<img src="/images/watermark.gif"...''' in files:

templates/identities.html
templates/messageerror.html
watermark.html

==== Enable Plug-ins ====

RoundCube has various useful plug-ins, which could be found in ''/usr/share/webapps/roundcube/plugins'' directory. For example you may want to enable ''password'' plug-in to let users change their passwords directly from RoundCube using an extra Password Tab added to User Settings.

* Grant limited permissions for ''roundcube'' database role
psql -U postgres postfix
postfix=# GRANT UPDATE (password,modified) ON mailbox TO roundcube;
postfix=# GRANT SELECT (username) ON mailbox TO roundcube;
postfix=# GRANT INSERT ON log TO roundcube;
postfix=# \q

* Setup ''password'' plug-in parameters in ''/usr/share/webapps/roundcube/plugins/password/config.inc.php''
mv /usr/share/webapps/roundcube/plugins/password/config.inc.php.dist /usr/share/webapps/roundcube/plugins/password/config.inc.php
vi /usr/share/webapps/roundcube/plugins/password/config.inc.php

<pre>
$rcmail_config['password_minimum_length'] = 7;
$rcmail_config['password_require_nonalpha'] = true;
...
$rcmail_config['password_db_dsn'] = 'pgsql://roundcube:<roundcube_password>@localhost/postfix';
...
$rcmail_config['password_query'] = "UPDATE mailbox set password = %c, modified = NOW() where username = %u; INSERT INTO log (timestamp,username,domain,action,data) VALUES (NOW(),%u || ' (' || %h || ')',%d,'edit_password',%u)";
</pre>

* Enable ''password'' plug-in
vi /usr/share/webapps/roundcube/config/main.inc.php

<pre>
...
$rcmail_config['plugins'] = array('password');
</pre>

* Enable ''create_default_folders'' for RoundCube
vi /usr/share/webapps/roundcube/config/main.inc.php

<pre>
...
$rcmail_config['create_default_folders'] = TRUE;
...
</pre>

=== OpenLDAP based Address Book ===

This OpenLDAP configuration uses the SQL backend, which represents information stored in PostgreSQL as an LDAP subtree for Address Book functionality for email lookups, user authentication or even replication account information between sites. This procedure uses some metainformation to translate LDAP queries to SQL queries, leaving relational schema untouched, which allows SQL and LDAP applications to inter-operate without replication, and exchange data as needed. The SQL backend uses UnixODBC to connect to PostgresSQL.

* Install OpenLDAP and ODBC

<pre>
apk add openldap libldap openldap-back-sql php-ldap unixodbc psqlodbc ca-certificates
</pre>

* Update "postfix" database (it will add 'id' columns to mailbox and domain tables, also will create tables and views to represent LDAP metainformation)

'''Note''': These instructions are for example domain example.com. So make sure you replaced all entries of 'example' and 'com' according to your domain name parts.

Put the following into a new file called '''script''':

<pre>
ALTER TABLE domain ADD COLUMN id SERIAL;
ALTER TABLE mailbox ADD COLUMN id SERIAL;

CREATE TABLE ldap_entry_objclasses (
entry_id integer NOT NULL,
oc_name character varying(64)
);

CREATE TABLE ldap_oc_mappings (
name character varying(64) NOT NULL,
keytbl character varying(64) NOT NULL,
keycol character varying(64) NOT NULL,
create_proc character varying(255),
delete_proc character varying(255),
expect_return integer NOT NULL
);

ALTER TABLE ldap_oc_mappings ADD COLUMN id SERIAL;
ALTER TABLE ldap_oc_mappings ADD PRIMARY KEY (id);

CREATE TABLE ldap_attr_mappings (
oc_map_id integer NOT NULL REFERENCES ldap_oc_mappings(id),
name character varying(255) NOT NULL,
sel_expr character varying(255) NOT NULL,
sel_expr_u character varying(255),
from_tbls character varying(255) NOT NULL,
join_where character varying(255),
add_proc character varying(255),
delete_proc character varying(255),
param_order integer NOT NULL,
expect_return integer NOT NULL
);

ALTER TABLE ldap_attr_mappings ADD COLUMN id SERIAL;
ALTER TABLE ldap_attr_mappings ADD PRIMARY KEY (id);

CREATE VIEW ldap_dcs AS
((SELECT (domain.id + 100000) AS id,
('dc='::text || replace((domain.domain)::text, '.'::text, ',dc='::text)) AS dn,
1 AS oc_map_id,
100000 AS parent,
0 AS keyval,
domain.domain
FROM domain
WHERE domain.domain <> 'ALL')
UNION
(SELECT 100000 AS id,
('dc=' || regexp_replace((domain.domain)::text, '.*\\.', ''::text)) AS dn,
1 AS oc_map_id,
0 AS parent,
0 AS keyval,
(regexp_replace((domain.domain)::text, '.*\\.', ''::text)) AS domain
FROM domain
WHERE domain.domain <> 'ALL'
LIMIT 1));

CREATE VIEW ldap_entries AS
SELECT mailbox.id,
((('cn='::text || initcap(replace(split_part((mailbox.username)::text, '@'::text, 1), '.'::text, ' '::text))) || ',dc='::text) ||
replace(regexp_replace((mailbox.username)::text, '.*@', ''::text), '.'::text, ',dc='::text)) AS dn,
1 AS oc_map_id,
(SELECT ldap_dcs.id
FROM ldap_dcs
WHERE ((ldap_dcs.domain)::text = (mailbox.domain)::text)) AS parent,
mailbox.id AS keyval
FROM mailbox
UNION
SELECT ldap_dcs.id,
ldap_dcs.dn,
ldap_dcs.oc_map_id,
ldap_dcs.parent,
ldap_dcs.keyval
FROM ldap_dcs;
</pre>
'''''Question to experts: Is this normal to have in this script "WARNING: nonstandard use of \\ in a string literal"?'''''

Finally, execute the commands in the file with:
cat script | psql -U postfix postfix
rm script

* Fill out LDAP tables according to following example (make sure to separate values with TABs):

Put the following into a new file called '''script''':

<pre>
COPY ldap_oc_mappings (id, name, keytbl, keycol, create_proc, delete_proc, expect_return) FROM stdin;
1 exampleBox mailbox id \N \N 1
\.
COPY ldap_attr_mappings (id, oc_map_id, name, sel_expr, sel_expr_u, from_tbls, join_where, add_proc, delete_proc, param_order, expect_return) FROM stdin;
1 1 displayName mailbox.name \N mailbox \N \N \N 3 0
2 1 mail mailbox.username \N mailbox \N \N \N 3 0
3 1 cn mailbox.name \N mailbox \N \N \N 3 0
4 1 userPassword '{CRYPT}'||mailbox.password \N mailbox \N \N \N 3 0
\.
</pre>

Finally, execute the commands in the file with:
cat script | psql -U postfix postfix
rm script

* Check that "ldap_dcs" view looks something like this:

<pre>
echo 'select * from ldap_dcs' | psql -U postgres postfix
</pre>

<pre>
id | dn | oc_map_id | parent | keyval | domain
--------+-----------------------------+-----------+--------+--------+--------------------
100000 | dc=com | 1 | 0 | 0 | com
100001 | dc=example,dc=com | 1 | 100000 | 0 | example.com
</pre>

* Check that "ldap_entries" view looks something like this:

<pre>
echo 'select * from ldap_entries' | psql -U postgres postfix
</pre>

<pre>
id | dn | oc_map_id | parent | keyval
--------+-------------------------------------------------------+-----------+--------+--------
1 | cn=address1,dc=example,dc=com | 1 | 100001 | 1
...
123 | cn=address123,dc=example,dc=com | 1 | 100001 | 1
100000 | dc=com | 1 | 0 | 0
100001 | dc=example,dc=com | 1 | 100000 | 0
</pre>

* Configure ODBC parameters

Edit /etc/odbc.ini:

<pre>
[PostgreSQL]
Description = Connection to Postgres
Driver = PostgreSQL
Trace = Yes
TraceFile = sql.log
Database = postfix
Servername = 127.0.0.1
UserName =
Password =
Port = 5432
Protocol = 6.4
ReadOnly = No
RowVersining = No
ShowSystemTables = No
ShowOidColumn = No
FakeOidIndex = No
ConnSettings =
</pre>

Edit /etc/odbcinst.ini:

<pre>
[PostgreSQL]
Description = PostgreSQL driver for Linux
Driver = /usr/lib/psqlodbcw.so
Setup = /usr/lib/libodbcpsqlS.so
FileUsage = 1
</pre>

* Test ODBC connection

<pre>
echo "select * from domain;" | isql PostgreSQL postgres
</pre>

* Provide permission to certificate for LDAP server

<pre>
chown ldap /etc/lighttpd/server-bundle.pem
</pre>

* Edit LDAP schema

Edit /etc/openldap/schema/example.com.schema:

<pre>
attributetype ( 0.9.2342.19200300.100.1.3
NAME ( 'mail' 'rfc822Mailbox' )
DESC 'RFC1274: RFC822 Mailbox'
EQUALITY caseIgnoreIA5Match
SUBSTR caseIgnoreIA5SubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} )

attributetype ( 2.16.840.1.113730.3.1.241
NAME 'displayName'
DESC 'RFC2798: preferred name to be used when displaying entries'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )

objectclass ( 2.16.840.1.113730.3.2.2
NAME 'exampleBox'
DESC 'example.com mailbox'
MUST ( displayName $ mail $ userPassword )
)

# RFC 1274 + RFC 2247
attributetype ( 0.9.2342.19200300.100.1.25
NAME ( 'dc' 'domainComponent' )
DESC 'RFC1274/2247: domain component'
EQUALITY caseIgnoreIA5Match
SUBSTR caseIgnoreIA5SubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )

attributetype ( 2.5.4.46 NAME 'dnQualifier'
DESC 'RFC2256: DN qualifier'
EQUALITY caseIgnoreMatch
ORDERING caseIgnoreOrderingMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
</pre>

* Configure LDAP server

Edit /etc/openldap/slapd.conf:

<pre>
include /etc/openldap/schema/example.com.schema
pidfile /var/run/openldap/slapd.pid
argsfile /var/run/openldap/slapd.args

# Uncomment next five TLS... lines if you want to use LDAPs (secured). Probably you don't want it...
#TLSCipherSuite HIGH
#TLSCACertificateFile /etc/lighttpd/ca-crt.pem
#TLSCertificateFile /etc/lighttpd/server-bundle.pem
#TLSCertificateKeyFile /etc/lighttpd/server-bundle.pem
#TLSVerifyClient never

# This is needed for proper representation of MD5-CRYPT format stored in database
# see more details in http://strugglers.net/~andy/blog/2010/01/23/openldap-and-md5crypt/
password-hash {CRYPT}
password-crypt-salt-format "$1$%.8s"

loglevel stats
moduleload /usr/lib/openldap/back_sql.so
sizelimit 3000

database sql

dbname PostgreSQL
dbuser postfix
dbpasswd *****

suffix "dc=example,dc=com"

upper_func "upper"
strcast_func "text"
concat_pattern "?||?"
has_ldapinfo_dn_ru no
lastmod off

access to attrs=userPassword by * auth

access to * by peername.ip=127.0.0.1 read
# by peername.ip=<IP>%<netmask> read
# by peername.ip=<IP> read
by users read
</pre>

* Set permissions for slapd.conf

<pre>
chown ldap:ldap /etc/openldap/slapd.conf
</pre>

* Configure startup parameters to make sure that LDAP server start AFTER PostgreSQL and listens on localhost with clear text and public IP with SSL. In case you uncommented TLS lines in slapd.conf use this string: OPTS="-h 'ldaps:// ldap://'"

Edit /etc/conf.d/slapd:

<pre>
rc_need="postgresql"
OPTS="-h 'ldap://'"
</pre>

* Start LDAP server

<pre>
rc-update add slapd default
/etc/init.d/slapd start
</pre>

* Configure LDAP client utilities. In case you uncommented TLS lines in slapd.conf replace ldap with ldaps

Edit /etc/openldap/ldap.conf

<pre>
BASE dc=example,dc=com
URI ldap://host.example.com

# Uncomment next three TLS... lines if you want to use LDAPs (secured). Probably you don't want it...
#TLS_CACERT /etc/lighttpd/ca-crt.pem
#TLS_CERT /etc/lighttpd/server-bundle.pem
#TLS_KEY /etc/lighttpd/server-bundle.pem
</pre>

* Test LDAP server

<pre>
ldapsearch -z 3
ldapsearch -z 3 -x -W -D cn=admin,dc=example,dc=com
ldapsearch -z 3 -x -W -D cn=address1,dc=example,dc=com
</pre>

* Configure RoundCube webmail for email lookups

In order to enable php-ldap support you need to restart lighttpd server

/etc/init.d/lighttpd restart

Edit /etc/roundcube/main.inc.php:

<pre>
$rcmail_config['ldap_debug'] = false;
...
$rcmail_config['address_book_type'] = 'sql';

$rcmail_config['ldap_public']['example.com'] = array(
'name' => 'example.com',
'hosts' => array('127.0.0.1'),
'port' => 389,
'use_tls' => false,
'user_specific' => false,
'base_dn' => 'dc=example,dc=com',
'bind_dn' => '',
'bind_pass' => '',
'writable' => false,
'LDAP_Object_Classes' => array("top", "exampleBox"),
'required_fields' => array("cn", "sn", "mail"),
'LDAP_rdn' => 'mail',
'ldap_version' => 3,
'search_fields' => array('mail', 'cn', 'sn', 'givenName'),
'name_field' => 'cn',
'email_field' => 'mail',
'surname_field' => 'sn',
'firstname_field' => 'gn',
'sort' => 'cn',
'scope' => 'sub',
'filter' => '(objectClass=*)', // Construct here any filter you need
'fuzzy_search' => true);

$rcmail_config['autocomplete_addressbooks'] = array('sql','example.com');
</pre>

* Fix PostfixAdmin to work with the new table definition

Edit /var/www/domains/example.com/www/postfixadmin/list-domain.php. Replace the line:
<pre>
SELECT domain.* , COUNT( DISTINCT mailbox.username ) AS mailbox_count
</pre>
With the lines:
<pre>
SELECT domain.domain, domain.description, domain.aliases, domain.mailboxes,
domain.maxquota, domain.quota, domain.transport, domain.backupmx, domain.created,
domain.modified, domain.active, COUNT( DISTINCT mailbox.username ) AS mailbox_count
</pre>

== log rotation ==

Ensure the busybox cron service is started and is configured to auto-start:

/etc/init.d/cron start
rc-update add cron default

Add log rotate:

apk add logrotate

Edit ''/etc/logrotate.conf'' as desired, but the defaults should be sufficient for most people.

== Optional: Configure Web Server Virtual Domains ==

'''Note:''' These steps can be done ''in addition to'' the default lighttpd configuration above, which allows you to access the ACF, PostfixAdmin and Roundcube interfaces as subfolders of one web service.

'''Note:''' If you provide SSL access for multiple domain site you may need to follow http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:SSL#SSL-on-multiple-domains in order to provide multi-domain certificates. If you would like to redirect hosts to their secure equivalents use the following instructions http://redmine.lighttpd.net/projects/lighttpd/wiki/HowToRedirectHttpToHttps.

This server hosts three separate web applications, and these can be handled as three ''different'' virtual domains on the same web server. They will be distinguished by their DNS names, so you can choose domains for the three separate services (or at least the ones you want to publish):

* ACF - Alpine Configuration Framework for managing the server
* PostfixAdmin - for managing the postfix installation
* RoundCube - for accessing individual mailboxes

Choose three different domains (from here on known as ACF_DOMAIN, POSTFIXADMIN_DOMAIN, and ROUNDCUBE_DOMAIN) and configure DNS for all three to point to the IP address of your host. These should be DNS '''A''' records.

Then, configure lighttpd to handle the three separate domains by editing /etc/lighttpd/lighttpd.conf:

<pre>
$HTTP["host"] == "ACF_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/ACF_DOMAIN/"
simple-vhost.document-root = "www/"
}

$HTTP["host"] == "POSTFIXADMIN_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/POSTFIXADMIN_DOMAIN/"
simple-vhost.document-root = "www/"
}

$HTTP["host"] == "ROUNDCUBE_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/ROUNDCUBE_DOMAIN/"
simple-vhost.document-root = "www/"
}
</pre>

And, then link the appropriate www directories.
<pre>
mkdir -p /var/www/domains/ACF_DOMAIN
ln -s /usr/share/acf/www /var/www/domains/ACF_DOMAIN/www

mkdir -p /var/www/domains/POSTFIXADMIN_DOMAIN
ln -s /var/www/domains/host.example.com/www/postfixadmin /var/www/domains/POSTFIXADMIN_DOMAIN/www

mkdir -p /var/www/domains/ROUNDCUBE_DOMAIN
ln -s /usr/share/webapps/roundcube /var/www/domains/ROUNDCUBE_DOMAIN/www
</pre>

== Optional: Enable compression in Lighttpd ==

* Uncomment ''mod_compress'' and ''mod_setenv'' and modify website section as follows

mkdir -p /var/lib/lighttpd/cache
chown lighttpd:lighttpd /var/lib/lighttpd/cache

vi /etc/lighttpd/lighttpd.conf

...
"mod_setenv",
"mod_compress",
...
$HTTP["host"] == "ROUNDCUBE_DOMAIN" {
...
static-file.etags = "enable"
etag.use-mtime = "enable"
$HTTP["url"] =~ "^/(plugins|skins|program)" { setenv.add-response-header = ( "Cache-Control" => "public, max-age=2592000") }
compress.cache-dir = var.statedir + "/cache/compress"
compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml", "image/gif", "image/png")
}

[[Category:Mail]]
[[Category:PHP]]
[[Category:SQL]]
[[Category:ACF]]

Small Office Services

2016-07-26T23:48:45Z

Ttrask: Add ACF category

'''Abstract''': This document will outline how to provide various network services for a small remote office, using Linux containerization (LXC). It is designed to be a complement to the [[Dynamic Multipoint VPN (DMVPN)|DMVPN]] spoke node.

The following services will be available in addition to the encrypted communications between offices provided by the DMVPN network:
* Internet browsing proxy server with domain filtering (wired clients on protected internal network)
* Separate proxy for wifi clients
* SIP phone system including web based provisioning and basic voicemail services

The assumption is made that the following VLANs and subnets are used as the DMVPN document did:

{|class="wikitable"
!'''Interface'''
!'''Description'''
!'''Subnet'''
|-
|bond0.3
|Management
|10.1.0.129/26
|-
|bond0.101
|LAN
|10.1.0.0/25
|-
|bond0.256
|Internet from ISP1
|Allocated from ISP
|-
|bond0.257
|Internet from ISP2
|Allocated from ISP
|-
|bond0.620
|Transit between wifi proxy and dmvpn spoke node
|10.1.0.252/30
|-
|bond0.701
|WiFi clients (no access to DMVPN network)
|172.17.48.0/24
|-
|bond0.1101
|Voice
|10.2.0.0/24
|}

{{Tip|At the time of writing, the recommended Alpine version for building the Host box for the containers should be at minimum 2.7.9 64 bit.}}

= Hardware =
For an office that will serve under 20 people, the following containers can easily run on low-power hardware such as a Via Nano 1.6Ghz Jetway board with 8GB RAM with dual 500GB SATA hard drives running in RAID 1 (software).

= Setup LXC Host Box =

== Boot Alpine USB ==
Follow the instructions on http://wiki.alpinelinux.org/wiki/Create_a_Bootable_USB about how to create a bootable USB.

== Alpine Setup ==
{{Cmd|setup-alpine}}

{|class="wikitable"
!'''You will be prompted something like this...'''
!'''Suggestion on what you could enter...'''
|-
|<code>Select keyboard layout [none]:</code>
|''Type an appropriate layout for you''
|-
|<code>Select variant:</code>
|''Type an appropriate layout for you (if prompted)''
|-
|<code>Enter system hostname (short form, e.g. 'foo') [localhost]:</code>
|''Enter the hostname, e.g.'' '''lxc-host'''
|-
|<code>Available interfaces are: eth0<br>Enter '?' for help on bridges, bonding and vlans.<br>Which one do you want to initialize? (or '?' done')</code>
|''Enter'' '''bond0.3'''
|-
|<code>Available bond slaves are: eth0 eth1<br>Which slave(s) do you want to add to bond0? (or 'done') [eth0]</code>
|'''eth0 eth1'''
|-
|<code>IP address for bond0? (or 'dhcp', 'none', '?') [dhcp]:</code>
|''Press Enter confirming 'none'''
|-
|<code>IP address for bond0.3? (or 'dhcp', 'none', '?') [dhcp]:</code>
|'''<%LXCHOST_MANAGEMENT_IP_ADDRESS%>'''
|-
|<code>Netmask? [255.255.255.0]:</code>
|'''<%DMVPN_MANAGEMENT_NETMASK%>'''
|-
|<code>Gateway? (or 'none') [none]:</code>
|'''<%DMVPN_MANAGEMENT_NET_IP%>'''
|-
|<code>Do you want to do any manual network configuration? [no]</code>
|'''no'''
|-
|<code>DNS domain name? (e.g. 'bar.com') []:</code>
|''Enter the domain name of your intranet, e.g.,'' '''office.example.net'''
|-
|<code>DNS nameservers(s)? []:</code>
|'''8.8.8.8 8.8.4.4''' (we will change them later)
|-
|<code>Changing password for root<br>New password:</code>
|''Enter a secure password for the console''
|-
|<code>Retype password:</code>
|''Retype the above password''
|-
|<code>Which timezone are you in? ('?' for list) [UTC]:</code>
|''Press Enter confirming 'UTC'''
|-
|<code>HTTP/FTP proxy URL? (e.g. 'http://proxy:8080', or 'none') [none]</code>
|''http://'''<%DMVPN_LAN_IP%>''':8080''
|-
|<code>Enter mirror number (1-9) or URL to add (or r/f/e/done) [f]:</code>
|''Select a mirror close to you and press Enter''
|-
|<code>Which SSH server? ('openssh', 'dropbear' or 'none') [openssh]:</code>
|''Press Enter confirming 'openssh'''
|-
|<code>Which NTP client to run? ('openntpd', 'chrony' or 'none') [chrony]:</code>
|''Press Enter confirming 'chrony'''
|-
|<code>Which disk(s) would you like to use? (or '?' for help or 'none') [none]:</code>
|'''sda sdb'''
|-
|<code>How would you like to use them? ('sys', 'data' or '?' for help):</code>
|'''data'''
|-
|<code>Enter where to store configs ('floppy', 'usb' or 'none') [usb]:</code>
|''Press Enter confirming 'usb'''
|-
|<code>Enter apk cache directory (or '?' or 'none') [/media/usb/cache]:</code>
|''Press Enter confirming '/media/usb/cache'''
|}

Upgrade packages
{{Cmd|apk update
apk upgrade}}

Save Changes
{{Cmd|lbu commit}}

Finish Setup with a reboot
{{Cmd|reboot}}

== Setup Networking ==
With your favorite editor configure /etc/network/interfaces
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

auto bond0
iface bond0 inet manual
bond-slaves eth0 eth1
bond-mode balance-tlb
bond-miimon 100
bond-updelay 500
up ip link set $IFACE up
down ip link set $IFACE down

auto bond0.3
iface bond0.3 inet static
address <%LXCHOST_MANAGEMENT_IP_ADDRESS%>
netmask <%DMVPN_MANAGEMENT_NETMASK%>
gateway <%DMVPN_MANAGEMENT_IP%>

auto bond0.101
iface bond0.101 inet manual
up ip link set $IFACE up
down ip link set $IFACE down

auto bond0.1101
iface bond0.1101 inet manual
up ip link set $IFACE up
down ip link set $IFACE down

auto bond0.701
iface bond0.701 inet manual
up ip link set $IFACE up
down ip link set $IFACE down
}}

Apply changes by restarting networking
{{Cmd|/etc/init.d/networking restart}}

== Enable IP Forwarding ==
{{Cmd|echo "1" > /proc/sys/net/ipv4/ip_forward}}
== Setup Firewall ==
{{Cmd|apk add acf-awall}}

With your favorite editor, create the base policy for the firewall
{{cat|/etc/awall/optional/base.json|
{
"description": "Management",

"policy": [
{ "in": "_fw", "action": "accept" }
],

"filter": [
{
"out": "_fw",
"service": [ "ssh", "https", "ping" ],
"action": "accept"
}
]
}
}}
Activate the firewall, and allow iptables to startup automatically at boot
{{Cmd|modprobe ip_tables
awall enable base
awall activate -f
rc-update add iptables}}

== Install LXC ==
Install the LXC and Bridge packages
{{Cmd|apk add lxc bridge}}
With your favorite editor configure /etc/lxc/default.conf
{{cat|/etc/lxc/default.conf|
## Allow containers in the same VLAN to see each other
lxc.network.type {{=}} macvlan
lxc.network.macvlan.mode {{=}} bridge
lxc.network.link {{=}} bond0.3
lxc.network.name {{=}} eth0

## Restrict capabilities of the containers
lxc.cap.drop {{=}} sys_admin audit_control audit_write fsetid ipc_lock
lxc.cap.drop {{=}} ipc_owner lease linux_immutable mac_admin mac_override
lxc.cap.drop {{=}} mknod setfcap setpcap sys_module sys_nice sys_pacct
lxc.cap.drop {{=}} sys_ptrace sys_rawio sys_tty_config sys_time
}}
Finish Installation
{{Cmd|lbu ci
reboot}}
= Install the Web Proxy Container =
== Create and Configure the container ==
{{Cmd|lxc-create -n webproxy -f /etc/lxc/default.conf -t alpine}}
Create the startup Script
{{Cmd|ln -s /etc/init.d/lxc /etc/init.d/lxc.webproxy}}

Edit the container's config file found at /var/lib/lxc/webproxy/config, to reflect the network for the web proxy container

{{cat|/var/lib/lxc/webproxy/config|
...
lxc.network.link {{=}} bond0.101
...
}}

Start the container
{{Cmd|/etc/iniit.d/lxc.webproxy}}

Configure the container to automatically start
{{Cmd|rc-update add lxc.webproxy}}

== Enter the webproxy container ==
{{Cmd|lxc-console -n webproxy}}
Login as root
{{Note|If the need arises to exit the container press {{Key| Ctrl}}+{{Key| a}} + {{Key| q}}}}
Remove obsolete /etc/network/interfaces
{{Cmd|rm /etc/network/interfaces}}
Create and configure the new /etc/network/interfaces as shown below:
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 10.1.0.2
netmask 255.255.255.192
gateway 10.1.0.1
}}

Startup networking
{{Cmd| /etc/init.d/networking start}}

Add rule to DMVPN awall policy to allow this proxy out to the internet
{{Note| this is to be configured on the DMVPN awall config}}
{{cat| /etc/awall/optional/internet-host.json|
{
"in": "B",
"src": "$10.1.0.2",
"out": "E",
"action": "accept",
},
}}

Configure remote administration
{{Cmd|apk update
setup-sshd -c openssh
sed -i "s/.PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sed -i "s/.UseDNS yes/UseDNS no/" /etc/ssh/sshd_config}}

Start ssh
{{Cmd|/etc/init.d/sshd start}}

Configure a passwd for the container
{{Cmd|passwd}}

Setup acf for web administration
{{Cmd|setup-acf}}

== Setup Firewall ==
{{Cmd|apk add acf-awall}}

With your favorite editor, create the policies for the firewall
{{cat|/etc/awall/optional/base.json|
{
"description": "Management",

"policy": [
{ "in": "_fw", "action": "accept" }
],

"filter": [
{
"out": "_fw",
"service": [ "ssh", "https", "ping" ],
"action": "accept"
}
]
}
}}
{{cat|/etc/awall/optional/webproxy.json|
{
"description": "Web Proxy",

"filter": [
{
"out": "_fw",
"service": [ "http", "http-alt" ],
"action": "accept"
}
]
}
}}
Activate the firewall, and allow iptables to startup automatically at boot
{{Cmd|awall enable base
awall enable webproxy
awall activate -f
rc-update add iptables
}}

== Install and Configure the Squid Web Proxy Service ==
Install the required packages
{{Cmd|apk add acf-squid squark acf-lighttpd}}

Configure /etc/squid/squid.conf, replace <%WEBPROXY_IP_ADDRESS%>, <%HOSTNAME%>, and <%DOMAIN%>
{{cat|/etc/init.d/squid/squid.conf|
<pre>
#Squid config for webproxy

# This port listens for client requests
http_port 8080

visible_hostname <%HOSTNAME%>.<%DOMAIN%>
cache_mem 8 MB
# If you don't have an HD installed comment the "cache_dir" line below
cache_dir aufs /var/cache/squid 900 16 256

# Even though we only use one proxy, this line is recommended
# More info: http://www.squid-cache.org/Versions/v2/2.7/cfgman/hierarchy_stoplist.html
hierarchy_stoplist cgi-bin ?

# Keep 7 days of access logs
logfile_rotate 7

logformat squark %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt %rG
access_log /var/log/squid/access.log squark
cache_store_log none
pid_filename /var/run/squid.pid

# Make sure client IP is passed to Squark
log_uses_indirect_client on
acl_uses_indirect_client on

# Fix for problems with branch file transfer application
# ignore_expect_100 on (deprecated)

# Debugging Squid, see http://wiki.squid-cache.org/KnowledgeBase/DebugSections
# for more info
# Keep 7 days of cache log
debug_options rotate=7

# Web auditors want to see the full uri, even with the query terms
strip_query_terms off

refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320

coredump_dir /var/cache/squid

#
# Authentication
#

#
# Access Control Lists (ACL's)
#

# Standard ACL settings
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp
acl to_localhost dst <%WEBPROXY_IP_ADDRESS%>
acl SSL_ports port 443 563 8004 9000
acl Safe_ports port 21 70 80 81 210 280 443 563 499 591 777 1024 1022 1025-65535
acl purge method PURGE
acl CONNECT method CONNECT

# Squark filter
url_rewrite_program /usr/bin/squark-filter
url_rewrite_children 1 concurrency=128

# Require authentication
acl userlist src all

# Definition of zones
acl Zone_B src <%LAN_SUBNET%>/<%LAN_SLASH_NOTATION%>
#acl Zone_D src <%WiFi_SUBNET%>/<%WiFi_SLASH_NOTATION%>

# Settings migrated from smn
acl Zone_B_AllowedUserDomains dstdomain "/etc/squid/alloweduserdomains"
acl Zone_B_AllowedServicesHosts src "/etc/squid/allowedserviceshosts"
acl Zone_B_AllowedServicesDomains dstdomain "/etc/squid/allowedservicesdomains"

# Settings migrated from services
acl AnonBrowsers browser "/etc/squid/anonbrowserlist"
acl AnonIPAddrs src "/etc/squid/anoniplist"
acl AnonDomain url_regex "/etc/squid/anondomainlist"

#
# Access restrictions
#

cache deny QUERY

# Only allow cachemgr access from localhost
http_access allow manager localhost
http_access deny manager

# Only allow purge requests from localhost
http_access allow purge localhost
http_access deny purge

# Deny requests to unknown ports
http_access deny !Safe_ports

# Deny CONNECT to other than SSL ports
http_access deny CONNECT !SSL_ports

# Allow hosts in Zone_B and Zone_C to access hosts listed in
# /etc/squid/alloweduserdomains
http_access allow Zone_B Zone_B_AllowedUserDomains

# Allow hosts listed in /etc/squid/allowedserviceshosts to
# access domains listed in /etc/squid/allowedservicesdomains
http_access allow Zone_B_AllowedServicesHosts Zone_B_AllowedServicesDomains

# Denying all access not explictly allowed
http_access deny all

##Squark URL rewriter
#Prevent squark from filtering itself
url_rewrite_access deny manager
url_rewrite_access deny to_localhost

#We do not want authentication for these sites:
url_rewrite_access deny Zone_B Zone_B_AllowedUserDomains
url_rewrite_access deny Zone_B Zone_B_AllowedServicesDomains

http_reply_access allow all
icp_access allow all
</pre>
}}

Configure /etc/lighttpd/lighttpd.conf, replace <%WEBPROXY_IP_ADDRESS%>
{{cat|/etc/lighttpd/lighttpd.conf|
<pre>
##############################################################################
# Default lighttpd.conf for Gentoo.
# $Header: /var/cvsroot/gentoo-x86/www-servers/lighttpd/files/conf/lighttpd.conf,v 1.3 2005/09/01 14:22:35 ka0ttic Exp $
###############################################################################
var.basedir = "/var/www/localhost"
var.logdir = "/var/log/lighttpd"
var.statedir = "/var/lib/lighttpd"

server.modules = (
"mod_access",
"mod_accesslog",
"mod_extforward"
)
include "mime-types.conf"

include "mod_cgi.conf"

server.username = "lighttpd"

server.groupname = "lighttpd"

server.document-root = var.basedir + "/squark"

server.pid-file = "/var/run/lighttpd.pid"

server.errorlog = var.logdir + "/error.log"

server.indexfiles = ("index.php", "index.html",
"index.htm", "default.htm")
server.follow-symlink = "enable"

static-file.exclude-extensions = (".php", ".pl", ".cgi", ".fcgi")

accesslog.filename = var.logdir + "/access.log"

url.access-deny = ("~", ".inc")

extforward.forwarder = ("<%WEBPROXY_IP_ADDRESS%>" => "trust")

</pre>
}}

Configure mod_cgi.conf
{{cat|/etc/lighttpd/mod_cgi.conf|
<pre>
###############################################################################
# mod_cgi.conf
# include'd by lighttpd.conf.
# $Header: /var/cvsroot/gentoo-x86/www-servers/lighttpd/files/conf/mod_cgi.conf,v 1.1 2005/08/27 12:36:13 ka0ttic Exp $
###############################################################################

#
# see cgi.txt for more information on using mod_cgi
#

server.modules += ("mod_cgi")

# NOTE: this requires mod_alias
alias.url = (
"/cgi-bin/" => var.basedir + "/cgi-bin/"
)

#
# Note that you'll also want to enable the
# cgi-bin alias via mod_alias (above).
#

$HTTP["url"] =~ "^/cgi-bin/" {
# disable directory listings
dir-listing.activate = "disable"
# only allow cgi's in this directory
cgi.assign = (
".pl" => "/usr/bin/perl",
".cgi" => "/usr/bin/haserl"
)
}
</pre>
}}

Link the Squark web pages to the Web server home directory
{{Cmd|ln -s /usr/share/squark/www/ /var/www/localhost/squark}}

Create a Squark group
{{Cmd|addgroup squark}}

Make 'squid' and 'lighttpd' users member of the group squark
{{Cmd|addgroup squid squark
addgroup lighttpd squark}}

Start lighttpd, and configure the service to start on when container is booted
{{Cmd|/etc/init.d/lighttpd start
rc-update add lighttpd}}

Start Squid, and configure to start at boot
{{Cmd|/etc/init.d/squid start
rc-update add squid}}

= Install the DHCP and DNS server Container =
== Create and Configure the container ==
{{Cmd|lxc-create -n dhcpdns -f /etc/lxc/default.conf -t alpine}}
Create the startup Script
{{Cmd|ln -s /etc/init.d/lxc /etc/init.d/lxc.dhcpdns}}

Edit the container's config file found at /var/lib/lxc/dhcpdns/config, to reflect the network for the web proxy container

{{cat|/var/lib/lxc/dhcpdns/config|
<pre>
#Management Network Config
lxc.network.type = macvlan
lxc.network.macvlan.mode = bridge
lxc.network.link = bond0.3
lxc.network.name = eth0

#WiFi Network Config
lxc.network.type = macvlan
lxc.network.macvlan.mode = bridge
lxc.network.link = bond0.701
lxc.network.name = eth1

#Voice Network Config
lxc.network.type = macvlan
lxc.network.macvlan.mode = bridge
lxc.network.link = bond0.1101
lxc.network.name = eth2
</pre>
}}

Start the container
{{Cmd|/etc/init.d/lxc.dhcpdns}}

Configure the container to automatically start
{{Cmd|rc-update add lxc.dhcpdns}}

== Enter the dhcpdns container ==
{{Cmd|lxc-console -n dhcpdns}}
Login as root
{{Note|If the need arises to exit the container press {{Key| Ctrl}}+{{Key| a}} + {{Key| q}}}}
Remove obsolete /etc/network/interfaces
{{Cmd|rm /etc/network/interfaces}}
Create and configure the new /etc/network/interfaces as shown below:
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

#Management VLAN
auto eth0
iface eth0 inet static
address 10.1.0.130
netmask 255.255.255.192

#WiFi VLAN
auto eth1
iface eth1 inet static
address 172.16.48.2
netmask 255.255.255.0

#Voice VLAN
auto eth2
iface eth2 inet static
address 10.2.0.2
netmask 255.255.255.0
gateway 10.2.0.1
up ip address add 10.2.0.3/24 dev eth0

}}

Startup networking
{{Cmd| /etc/init.d/networking start}}

Configure and enable proxy settings
{{Cmd|setup-proxy http://10.1.0.2:8080
. /etc/profile.d/proxy.sh}}

Configure remote administration
{{Cmd|apk update
setup-sshd -c openssh
sed -i "s/.PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sed -i "s/.UseDNS yes/UseDNS no/" /etc/ssh/sshd_config}}

Start ssh
{{Cmd|/etc/init.d/sshd start}}

Configure a passwd for the container
{{Cmd|passwd}}

Setup acf for web administration
{{Cmd|setup-acf}}

== Setup Firewall ==
{{Cmd|apk add acf-awall}}

With your favorite editor, create the policies for the firewall
{{cat|/etc/awall/optional/base.json|
{
"description": "Management",

"policy": [
{ "in": "_fw", "action": "accept" }
],

"filter": [
{
"out": "_fw",
"service": [ "ssh", "https", "ping" ],
"action": "accept"
}
]
}
}}
{{cat|/etc/awall/optional/dhcp.json|
{
"description": "DHCP",

"filter": [
{
"out": "_fw",
"service": "dhcp",
"action": "accept"
}
]
}
}}
{{cat|/etc/awall/optional/dns.json|
{
"description": "DNS",

"filter": [
{
"out": "_fw",
"service": "dns",
"action": "accept"
}
]
}
}}
Activate the firewall, and allow iptables to startup automatically at boot
{{Cmd|awall enable base
awall enable dhcp
awall enable dns
awall activate -f
rc-update add iptables
}}

== Install and Configure DHCP and DNS services ==
install the dhcpd package
{{Cmd|apk add acf-dhcp}}
Create a new dhcpd.conf file
{{cat|/etc/dhcp/dhcpd.conf|
<pre>
## Common settings
default-lease-time 302400;
max-lease-time 604800;
ddns-update-style none;
log-facility local7;
authoritative;

## Common options
option time-servers 10.2.0.1;
option boot-server code 66 = string;

## Voice
subnet 10.2.0.0 netmask 255.255.255.0
{
range "10.2.0.20 10.2.0.250";
option domain-name-servers 10.2.0.2;
option routers 10.2.0.1;
option boot-server "http://10.2.0.4";
option domain-name "office.example.net";
}

## WiFi
subnet 172.17.48.0 netmask 255.255.255.0
{
range "172.17.48.10 172.17.48.250";
option routers 172.17.48.1;
option domain-name-servers 172.17.48.1;
}
</pre>
}}
Start DHCP service and add to runlevel default
{{Cmd|rc-service dhcpd start
rc-update add dhcpd}}

Install nsd and unbound packages
{{Cmd|apk add unbound }}

Remove unbound.conf
{{Cmd|rm /etc/unbound/unbound.conf}}

Create with your favorite editor a new configuration for unbound
{{cat|/etc/unbound/unbound.conf|
#Recursive DNS configuration

server:
interface: 10.2.0.2
do-not-query-localhost: no
verbosity: 1
do-ip4: yes
do-ip6: no
do-udp: yes
do-tcp: yes
do-daemonize: yes
access-control: 10.1.0.0/16 allow
access-control: 127.0.0.0/8 allow

#use the root.hints file to determine where to send DNS queries outside of network
root-hints: "/etc/unbound/root.hints"

stub-zone:
name: "office.example.net"
stub-addr: 10.2.0.3

stub-zone:
name: "example.net"
stub-addr: 172.16.255.1
stub-addr: 172.16.255.2
stub-addr: 172.16.255.3
stub-addr: 172.16.255.4
stub-addr: 172.16.255.5
stub-addr: 172.16.255.7

stub-zone:
name: "example2.net"
stub-addr: 172.16.255.1
stub-addr: 172.16.255.2
stub-addr: 172.16.255.3
stub-addr: 172.16.255.4
stub-addr: 172.16.255.5
stub-addr: 172.16.255.7

}}
Start Unbound and allow the container to use it
{{Cmd|/etc/init.d/unbound start
rc-update add unbound
echo nameserver 10.2.0.2 > /etc/resolv.conf

Install nsd
{{Cmd|apk add nsd}}
Configure nsd configuration
{{cat|/etc/nsd/nsd.conf|
server:
ip-address: 10.2.0.3
port: 53
server-count: 1
ip4-only: yes
hide-version: yes
identity: ""
zonesdir: "/etc/nsd"
zone:
name: office.example.net
zonefile: office.example.net.zone
}}

Configure Zone file for nsd
{{cat|/etc/nsd/nsd.conf|
$ORIGIN office.example.net.
$TTL 86400

@ IN SOA ns admin (
2013032200 ; Serial number [yyyymmddnn]
28800 ; Refresh
7200 ; Retry
864000 ; Expire
86400 ; Min TTL
)

@ NS ns1
; NSA Servers
ns1 IN A 10.2.0.3

;A Records for SIP Devices
sip IN A 10.2.0.4
media IN A 10.2.0.5

;NAPTR Records
sip IN NAPTR 10 1 "s" "SIP+D2U" "" _sip._udp.sip.office.example.net.

;SIP SRV Record
_sip._udp.sip IN SRV 10 100 5060 sip
}}

Check nsd configuration and start service
{{Cmd|nsd-checkconf /etc/nsd/nsd.conf
/etc/init.d/nsd start
rc-update add nsd}}

= Install the SIP Container =

== Create and Configure the container ==
{{Cmd|lxc-create -n sip -f /etc/lxc/default.conf -t alpine}}
Create the startup Script
{{Cmd|ln -s /etc/init.d/lxc /etc/init.d/lxc.sip}}

Edit the container's config file found at /var/lib/lxc/sip/config, to reflect the network for the sip container

{{cat|/var/lib/lxc/sip/config|
...
lxc.network.link {{=}} bond0.1101
...
}}

Start the container
{{Cmd|/etc/iniit.d/lxc.sip}}

Configure the container to automatically start
{{Cmd|rc-update add lxc.sip}}

== Enter the sip container ==
{{Cmd|lxc-console -n sip}}
Login as root
{{Note|If the need arises to exit the container press {{Key| Ctrl}}+{{Key| a}} + {{Key| q}}}}
Remove obsolete /etc/network/interfaces
{{Cmd|rm /etc/network/interfaces}}
Create and configure the new /etc/network/interfaces as shown below:
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 10.2.0.4
netmask 255.255.255.0
gateway 10.2.0.1
}}

Startup networking
{{Cmd| /etc/init.d/networking start}}

Configure and enable proxy settings
{{Cmd|setup-proxy http://10.1.0.2:8080
. /etc/profile.d/proxy.sh}}

Configure remote administration
{{Cmd|apk update
setup-sshd -c openssh
sed -i "s/.PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sed -i "s/.UseDNS yes/UseDNS no/" /etc/ssh/sshd_config}}

Start ssh
{{Cmd|/etc/init.d/sshd start}}

Configure a passwd for the container
{{Cmd|passwd}}

Setup acf for web administration
{{Cmd|setup-acf}}

== Setup Firewall ==
{{Cmd|apk add acf-awall}}

With your favorite editor, create the policies for the firewall
{{cat|/etc/awall/optional/base.json|
{
"description": "Management",

"policy": [
{ "in": "_fw", "action": "accept" }
],

"filter": [
{
"out": "_fw",
"service": [ "ssh", "https", "ping" ],
"action": "accept"
}
]
}
}}
{{cat|/etc/awall/optional/sip.json|
{

"description": "Phone System",

"filter": [
{
"out": "_fw",
"service": [ "sip", "sip-tls" ],
"action": "accept",
}
]

}
}}
{{cat|/etc/awall/optional/syslog.json|
{

"description": "Syslog server",

"filter": [
{
"out": "_fw",
"service": "syslog",
"action": "accept"
}
]

}
}}
Activate the firewall, and allow iptables to startup automatically at boot
{{Cmd|awall enable base
awall enable sip
awall enable syslog
awall activate -f
rc-update add iptables
}}

==Install and Configure Postgresql==
Install postgresql package
{{Cmd|apk update
apk add acf-postgresql}}
Prepare the database
{{Cmd|/etc/init.d/postgresql setup}}
Configure /var/lib/postgresql/9.3/data/postgresql.conf to set the 'log_destination' variable to show:
{{cat|/var/lib/postgresql/9.3/data/postresql.conf|
..
log_destination {{=}}'syslog'
}}
Start up the database and configure postgresql to start at boot up
{{Cmd|/etc/init.d/postgresql start
rc-update add postgresql}}

== Install acf-provisioning ==
* vi /etc/kamailio/kamctlrc
<pre>
SIP_DOMAIN=sip.office.example.net
DBENGINE=PGSQL
DBHOST=127.0.0.1
DBNAME=openser
DBRWUSER=openser
DBRWPW="openser"
DBROUSER=openserro
DBROPW=openserro
DBROOTUSER="postgres"
</pre>
* yes | kamdbctl create openser
* apk add acf-provisioning lua-socket lua-expat
* Create /etc/provisioning/update_device_params.lua:
<pre>
-- This is the script run after editing device params - basically only worried about extension and password
local functions, params, oldparams = ...

require("posix")
require("luasql.postgres")

local root = "/var/www/provisioning/htdocs/"
local b62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

APP.logevent("got to update_device_params script")

local function generatepw()
-- generate a random 12-character alphanumeric string
local file = io.open("/dev/urandom")
local str = ""
if file == nil then return nil end
local size = 12
while (size > 0 ) do
local offset = (string.byte(file:read(1)) % 62) + 1
str = str .. string.sub (b62, offset, offset)
size = size - 1
end
return str
end

local function findip(mac)
if not mac or mac == "" then
return nil
end
local ipaddr = functions.getselectresponse("SELECT ip FROM provisioning_requests WHERE mac~*'"..mac.."'")
if ipaddr and ipaddr[1] then
return ipaddr[1].ip
end
end

local function addfuturenotify(ipaddr, extension)
local res, err = pcall(function()
functions.runsqlcommand("DELETE FROM notify WHERE ipaddr='"..ipaddr.."' AND extension='"..extension.."'")
end)
if not res and err then
if string.match(err, "relation \"(%S+)\" does not exist") then
functions.runsqlcommand("CREATE TABLE notify (ipaddr text, extension text, seasoned boolean DEFAULT false)")
else
assert(res, err)
end
end
-- if table missing, create it and delete again
functions.runsqlcommand("INSERT INTO notify VALUES('"..ipaddr.."', '"..extension.."')")
end

local notify_device = function(mac, extension)
local ipaddr = findip(mac)
if ipaddr then
APP.logevent("Notifying "..ipaddr.." to update for "..(mac or ""))
os.execute("/etc/provisioning/notify_device "..ipaddr.." "..extension)
addfuturenotify(ipaddr, extension)
else
APP.logevent("Warning - could not find IP address for "..(mac or ""))
end
end

local kam = APP:new("kamailio/kamailio")

-- A table of devices to notify to update
local devices = {}

-- First, we check the registration numbers / passwords to 1) set a random password (if necessary) 2) make sure password matches any other registrations to same extension 3) push changes (add / delete / or update) to Kam database
-- Because this script also handles when device classes change, we have to consider that extensions are added / removed
local regs = {}
local forwarding = {"forwardnoanswerenable", "forwardnoanswer", "forwardbusyenable", "forwardbusy", "forwardallenable", "forwardall"}
local forwardsettings = {} -- Collect forwarding settings
local passwords = {} -- Collect old extension/password pairs
for name,val in pairs(params.value) do
if not regs[name] and string.match(name, "^reg") then
regs[name] = true
end
end
oldparams = oldparams or {value={}}
for name,val in pairs(oldparams.value) do
if string.match(name, "^reg") then
if val.value and val.value.extension and val.value.password then
passwords[val.value.extension.value] = val.value.password.value
end
if val.value and val.value.extension then
local fwd = {}
for i,f in ipairs(forwarding) do
if val.value[f] then
fwd[f] = val.value[f].value
end
end
forwardsettings[val.value.extension.value] = fwd
end
if not regs[name] then
regs[name] = true
end
end

end
local extension_id = params.value.reg1.value.extension.param_id
local password_id = params.value.reg1.value.password.param_id
functions.runsqlcommand("BEGIN TRANSACTION")
for name,val in pairs(regs) do
local new = ""
local old = ""
if params.value[name] then new = params.value[name].value.extension.value end
if oldparams.value[name] then old = oldparams.value[name].value.extension.value end
if new ~= old then
-- Extension changed
-- First, let's remove the stuff for the old extension
if old ~= "" then
local others = functions.getselectresponse("SELECT count(*) FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..old.."'")
if others[1].count == "0" then
APP.logevent("Removing old registration "..old)
-- remove the registration
kam.model.delete_user(old)
end
end
-- Now, add the new extension
if new ~= "" then
local pass
if params.value[name].value.password.value ~= "" and (not oldparams.value[name] or (oldparams.value[name].value.password.value ~= params.value[name].value.password.value)) then
-- The password parameter was changed and not blank, so use it
pass = params.value[name].value.password.value
APP.logevent("Added a new registration "..new.." with specified password "..pass)
-- There may be other devices with this extension
local others = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id=(SELECT param_id FROM provisioning_params WHERE name='mac') AND device_id IN (SELECT device_id FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
for i,o in ipairs(others) do
-- We'll notify whether it changed or not
devices[o.value] = new
end
elseif passwords[new] then
pass = passwords[new]
APP.logevent("Added a new registration "..new.." with reused password "..pass)
else
local others = functions.getselectresponse("SELECT * FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."' AND device_id!='"..params.value.device_id.value.."'")
-- If this is a new registration, use a new password
if #others == 0 then
pass = generatepw()
APP.logevent("Added a new registration "..new.." with random password "..pass)
else
-- Use the old password
local p = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id='"..password_id.."' AND device_id='"..others[1].device_id.."' AND group_name='"..others[1].group_name.."' LIMIT 1")
pass = p[1].value
APP.logevent("Added a new registration "..new.." with reused password "..pass)
end
end
passwords[new] = pass
params.value[name].value.password.value = pass
functions.runsqlcommand("DELETE FROM provisioning_values WHERE param_id='"..password_id.."' AND (device_id, group_name) IN (SELECT device_id, group_name FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
functions.runsqlcommand("INSERT INTO provisioning_values (SELECT device_id, group_name, '"..password_id.."', '"..pass.."' FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
local u = kam.model.get_user(new)
if u.value.username.errtxt then
-- Add this registration to Kam
local u = kam.model.get_new_user()
u.value.username.value = new
u.value.password.value = pass
u.value.password_confirm.value = pass
kam.model.create_new_user(u)
else
u.value.password.value = pass
u.value.password_confirm.value = pass
kam.model.update_user(u)
end
-- Let's also look at the forwarding settings
local change = false
local supported = false
local fwd = {}
for i,f in ipairs(forwarding) do
if params.value[name].value[f] then
supported = true
fwd[f] = params.value[name].value[f].value
if ((not oldparams.value[name] or not oldparams.value[name].value[f]) and (params.value[name].value[f].value ~= params.value[name].value[f].default)) or
(oldparams.value[name] and oldparams.value[name].value[f] and (params.value[name].value[f].value ~= oldparams.value[name].value[f].value)) then
change = true
end
end
if change then
local others = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id=(SELECT param_id FROM provisioning_params WHERE name='mac') AND device_id IN (SELECT device_id FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
for i,o in ipairs(others) do
-- We'll notify whether it changed or not
devices[o.value] = new
end
end
end
if supported then
if not change and forwardsettings[new] then
fwd = forwardsettings[new]
elseif not change then
-- This is a new extension, and the forwarding has not been set. We should check to see if there are any other devices with this extension
local others = functions.getselectresponse("SELECT * FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."' AND device_id!='"..params.value.device_id.value.."'")
if #others > 0 then
-- Use the existing settings
for i,f in ipairs(forwarding) do
local v = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id='"..params.value[name].value[f].param_id.."' AND device_id='"..others[1].device_id.."' AND group_name='"..others[1].group_name.."' LIMIT 1")
if #v > 0 then
fwd[f] = v[1].value
else
fwd[f] = params.value[name].value[f].default
end
end
end
end
if not change then
for i,f in ipairs(forwarding) do
params.value[name].value[f].value = fwd[f]
end
end
forwardsettings[new] = fwd
for i,f in ipairs(forwarding) do
functions.runsqlcommand("DELETE FROM provisioning_values WHERE param_id='"..params.value[name].value[f].param_id.."' AND (device_id, group_name) IN (SELECT device_id, group_name FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
if fwd[f] ~= params.value[name].value[f].default then
functions.runsqlcommand("INSERT INTO provisioning_values (SELECT device_id, group_name, '"..params.value[name].value[f].param_id.."', '"..tostring(fwd[f]).."' FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
end
end
end
end
elseif params.value[name] and oldparams.value[name] and params.value[name].value.extension.value ~= "" then
if params.value[name].value.password.value ~= oldparams.value[name].value.password.value then
-- Password changed - make any other registrations to this extension also change
local pass = params.value[name].value.password.value
if pass and pass ~= "" then
APP.logevent("Password changed for "..new.." from "..oldparams.value[name].value.password.value.." to "..pass)
else
pass = generatepw()
APP.logevent("Password cleared for "..new..", so set new random password "..pass)
end
passwords[new] = pass
functions.runsqlcommand("DELETE FROM provisioning_values WHERE param_id='"..password_id.."' AND (device_id, group_name) IN (SELECT device_id, group_name FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
functions.runsqlcommand("INSERT INTO provisioning_values (SELECT device_id, group_name, '"..password_id.."', '"..pass.."' FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
local u = kam.model.get_user(new)
u.value.password.value = params.value[name].value.password.value
u.value.password_confirm.value = params.value[name].value.password.value
kam.model.update_user(u)
-- Have to notify those other devices too
local others = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id=(SELECT param_id FROM provisioning_params WHERE name='mac') AND device_id IN (SELECT device_id FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
for i,o in ipairs(others) do
devices[o.value] = new
end
end
local change = false
local fwd = {}
for i,f in ipairs(forwarding) do
if params.value[name].value[f] and (not oldparams.value[name].value[f] or params.value[name].value[f].value ~= oldparams.value[name].value[f].value) then
change = true
break
end
end
if change then
-- Forwarding settings changed - make any other registrations to this extension also change
for i,f in ipairs(forwarding) do
functions.runsqlcommand("DELETE FROM provisioning_values WHERE param_id='"..params.value[name].value[f].param_id.."' AND (device_id, group_name) IN (SELECT device_id, group_name FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
if params.value[name].value[f].value ~= params.value[name].value[f].default then
functions.runsqlcommand("INSERT INTO provisioning_values (SELECT device_id, group_name, '"..params.value[name].value[f].param_id.."', '"..tostring(params.value[name].value[f].value).."' FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
end
end
-- Have to notify those other devices too
local others = functions.getselectresponse("SELECT value FROM provisioning_values WHERE param_id=(SELECT param_id FROM provisioning_params WHERE name='mac') AND device_id IN (SELECT device_id FROM provisioning_values WHERE param_id='"..extension_id.."' AND value='"..new.."')")
for i,o in ipairs(others) do
devices[o.value] = new
end
end
end
end
functions.runsqlcommand("COMMIT")

-- If reg1 or freepstn changed, then need to change free-pstn in kam
-- Since there can be multiple devices with the same reg1, we can't rely on params and oldparams
-- Check both reg's
--APP.logevent(session.serialize("params", params))
local reg = {}
if oldparams.value.reg1 and oldparams.value.reg1.value.extension and oldparams.value.reg1.value.extension.value ~= "" then
reg[oldparams.value.reg1.value.extension.value] = false
end
if params.value.reg1 and params.value.reg1.value.extension and params.value.reg1.value.extension.value ~= "" then
local pstn = false
if params.value.routing and params.value.routing.value.freepstn then
pstn = params.value.routing.value.freepstn.value
end
reg[params.value.reg1.value.extension.value] = pstn
end

APP.logevent("Looking at free-pstn")
for r,f in pairs(reg) do
-- if we're not sure, check provisioning database
if not f then
-- Most devices will have free-pstn due to class-of-service, but can be overridden, so this can get tricky
-- Check all devices where reg1 extension = r, and see what the freepstn value is for each
local others = functions.getselectresponse("SELECT CASE WHEN v.value IS NOT NULL THEN v.value WHEN g2p.value IS NOT NULL THEN g2p.value ELSE p.value END AS value "..
"FROM (devices_to_classes d2t JOIN provisioning_classes t USING(class_id) JOIN classes_to_param_groups t2g USING (class_id) JOIN provisioning_groups g USING(group_id) "..
"JOIN param_groups_to_params g2p USING(group_id) JOIN provisioning_params p USING(param_id)) LEFT JOIN provisioning_values v ON (d2t.device_id=v.device_id AND p.param_id=v.param_id AND g.name=v.group_name ) "..
"WHERE p.name='freepstn' AND d2t.device_id IN (SELECT device_id FROM provisioning_values WHERE param_id='"..extension_id.."' AND group_name='reg1' AND value='"..r.."')")
for i,o in ipairs(others) do
-- Now check the freepstn value for each one
if o.value == "true" then
f = true
break
end
end
end
-- Now, check the Kamailio group table
local alreadythere = false
local entries = kam.model.list_table_entries("grp")
for i,e in ipairs(entries.value.entries.value) do
if e.username == r then
alreadythere = true
if not f then
APP.logevent("Removing free-pstn for "..r)
-- Remove free-pstn from the old extension
kam.model.delete_table_entry("grp", e.id)
end
break
end
end
if f and not alreadythere then
APP.logevent("Adding free-pstn for "..r)
-- Add free-pstn to the new extension
local e = kam.model.get_table_entry("grp")
e.value.username.value = r
e.value.domain.value = ""
e.value.grp.value = "free-pstn"
e.value.last_modified.value = os.date("%c")
kam.model.create_table_entry(e)
end
end

kam:destroy()

-- If the mac address changed for Polycom with valid MAC (not blank or all 0's), we need to move the associated config files
if oldparams.value.device and oldparams.value.device.value.mac and oldparams.value.device.value.mac.value ~= "" and params.value.device and params.value.device.value.mac and params.value.device.value.mac.value ~= oldparams.value.device.value.mac.value then
if string.match(oldparams.value.device.label, "Polycom") and string.match(oldparams.value.device.value.mac.value, "[1-9A-F]") then
local deletefiles = true
if string.match(params.value.device.value.mac.value, "[1-9A-F]") then
--APP.logevent("Moving files for "..oldparams.value.device.value.mac.value)
deletefiles = false
else
--APP.logevent("Deleting files for "..oldparams.value.device.value.mac.value)
end
local path = root.."Polycom/"
if posix.stat(path, "type") == "directory" then
for d in posix.files(path) do
if string.match(d, string.lower(oldparams.value.device.value.mac.value)) and posix.stat(path..d, "type") == "regular" then
local newfile = string.gsub(d, string.lower(oldparams.value.device.value.mac.value), string.lower(params.value.device.value.mac.value))
if deletefiles then
--APP.logevent("deleting "..path..d)
os.remove(path..d)
else
--APP.logevent("moving "..path..d.." to "..path..newfile)
os.rename(path..d, path..newfile)
end
end
end
end
end
end

-- Then, notify the phone to pull it's config
-- Try to get a valid extension currently on the device
local oldexten = ""
for name,val in pairs(oldparams.value) do
if string.match(name, "^reg") and val.value.extension and val.value.extension.value ~= "" then
oldexten = val.value.extension.value
break
end
end
if params.value.device and params.value.device.value.mac and params.value.device.value.mac.value ~= "" then
devices[params.value.device.value.mac.value] = oldexten
end
if oldparams.value.device and oldparams.value.device.value.mac and oldparams.value.device.value.mac.value ~= "" then
devices[oldparams.value.device.value.mac.value] = oldexten
end

for name,value in pairs(devices) do
notify_device(name,value)
end
</pre>
* Create /etc/provisioning/provisioning_db_script
<pre>
#!/usr/bin/lua

local path = "PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin "
local creation_script = {
-- Parameters
"INSERT INTO provisioning_params VALUES(default, 'freepstn', 'boolean', 'Free PSTN Access', '', 'false', '200', '')",

-- Parameter Groups
"INSERT INTO provisioning_groups VALUES(default, 'routing', 'Free PSTN Access', '31')",
"INSERT INTO provisioning_groups VALUES(default, 'routing', 'No Free PSTN Access', '32')",

-- param_groups_to_params (group_id, param_id, value, editable)
"INSERT INTO param_groups_to_params VALUES((SELECT group_id FROM provisioning_groups WHERE label='Free PSTN Access'), (SELECT param_id FROM provisioning_params WHERE name='freepstn'), 'true', false)",
"INSERT INTO param_groups_to_params VALUES((SELECT group_id FROM provisioning_groups WHERE label='No Free PSTN Access'), (SELECT param_id FROM provisioning_params WHERE name='freepstn'), 'false', false)",

-- Classes
-- provisioning_class_groups (class_group_id, name, label, seq)
"INSERT INTO provisioning_class_groups VALUES(default, 'routing', 'Routing', '3')",

-- provisioning_classes (class_id, class_group_id, label, seq)
"INSERT INTO provisioning_classes VALUES(default, (SELECT class_group_id FROM provisioning_class_groups WHERE name='routing'), 'Free PSTN Access', '1')",
"INSERT INTO provisioning_classes VALUES(default, (SELECT class_group_id FROM provisioning_class_groups WHERE name='routing'), 'No Free PSTN Access', '2')",

-- classes_to_param_groups (class_id, group_id)
"INSERT INTO classes_to_param_groups VALUES((SELECT class_id FROM provisioning_classes WHERE label='Free PSTN Access'), (SELECT group_id FROM provisioning_groups WHERE label='Free PSTN Access'))",
"INSERT INTO classes_to_param_groups VALUES((SELECT class_id FROM provisioning_classes WHERE label='No Free PSTN Access'), (SELECT group_id FROM provisioning_groups WHERE label='No Free PSTN Access'))",

-- provisioning_options
"INSERT INTO provisioning_options VALUES((SELECT param_id FROM provisioning_params WHERE name='polycomringtone'), 'Warble', '15', '15')",
"INSERT INTO provisioning_options VALUES((SELECT param_id FROM provisioning_params WHERE name='polycomringtone'), 'Analog Ring', '16', '16')",
}

local f = io.popen("/usr/share/acf/www/cgi-bin/cli /provisioning/provisioning/getdevicevalues")
print(f:read("*a"))
f:close()
for i,c in ipairs(creation_script) do
print(path..'psql -U postgres -c "'..c..'" provisioning 2>&1')
local f = io.popen(path..'psql -U postgres -c "'..c..'" provisioning 2>&1')
print(f:read("*a"))
f:close()
end
</pre>
* chmod 755 /etc/provisioning/provisioning_db_script
* /etc/provisioning/provisioning_db_script
* echo '* * * * * run-parts /etc/periodic/1min' >> /etc/crontabs/root
* mkdir /etc/periodic/1min/
* /etc/periodic/1min/notify_device
<pre>
#!/usr/bin/lua

-- Load libraries
require("luasql.postgres")

-- Set variables
local DatabaseName = "provisioning"
local DatabaseUser = "postgres"
local DatabasePassword

local path = "PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin "
local env
local con

-- ################################################################################
-- LOCAL FUNCTIONS
local function assert (v, m)
if not v then
m = m or "Assertion failed!"
error(m, 0)
end
return v, m
end

-- Escape special characters in sql statements
local escape = function(sql)
sql = sql or ""
sql = string.gsub(sql, "'", "''")
return string.gsub(sql, "\\", "\\\\")
end

local databaseconnect = function()
if not con then
-- create environment object
env = assert (luasql.postgres())
-- connect to data source
local err
con, err = assert(env:connect(DatabaseName, DatabaseUser, DatabasePassword))
return true
end
return false
end

local databasedisconnect = function()
if env then
env:close()
env = nil
end
if con then
con:close()
con = nil
end
end

local getselectresponse = function(sql)
local retval = {}
local cur = assert (con:execute(sql))
local row = cur:fetch ({}, "a")
while row do
local tmp = {}
for name,val in pairs(row) do
tmp[name] = val
end
retval[#retval + 1] = tmp
row = cur:fetch (row, "a")
end
cur:close()
return retval
end

databaseconnect()

-- First, let's notify for the seasoned requests
local reqs = getselectresponse("SELECT * FROM notify WHERE seasoned='true'")
for i,r in ipairs(reqs) do
os.execute("/etc/provisioning/notify_device "..r.ipaddr.." "..r.extension)
end

-- Then mark any others as seasoned
assert(con:execute("DELETE FROM notify WHERE seasoned='true'"))
assert(con:execute("UPDATE notify SET seasoned='true' WHERE seasoned='false'"))

databasedisconnect()
</pre>
* apk add lighttpd
* rm /etc/lighttpd/lighttpd.conf
* ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf
* /etc/lighttpd/mod_cgi.conf:
<pre>
###############################################################################
# mod_cgi.conf
# include'd by lighttpd.conf.
# $Header: /var/cvsroot/gentoo-x86/www-servers/lighttpd/files/conf/mod_cgi.conf,v 1.1 2005/08/27 12:36:13 ka0ttic Exp $
###############################################################################

#
# see cgi.txt for more information on using mod_cgi
#

server.modules += ("mod_cgi")

# NOTE: this requires mod_alias
alias.url = (
"/cgi-bin/" => var.basedir + "/cgi-bin/"
)

#
# Note that you'll also want to enable the
# cgi-bin alias via mod_alias (above).
#

$HTTP["url"] =~ "^/cgi-bin/" {
# disable directory listings
dir-listing.activate = "disable"
# only allow cgi's in this directory
cgi.assign = (
".pl" => "/usr/bin/perl",
".cgi" => "",
"" => ""
)
}

# vim: set ft=conf foldmethod=marker et :
</pre>
* /etc/init.d/lighttpd start
* rc-update add lighttpd

* Customize provisioning:
<pre>
Parameter Default Value
registrar IP address or host name of SIP Router(s)
digitmap Digit map for your phone system (See Polycom Digit Map Reference)
digitmaptimeout Timeout in seconds corresponding to digitmap
sntpserver 10.2.0.1 (DMVPN spoke node)
timezone Timezone information for this location - see below
musiconhold SIP uri of the music-on-hold service - moh@media.office.example.net
adminpassword Administration password for advanced settings on phone (on-screen and web interface)
</pre>
* apk fetch --stdout acf-provisioning-polycom | tar -C / -zx
* Create a test Polycom device and boot it in the voice network to verify that it works

== Install Kamailio ==
* apk add kamailio kamailio-presence kamailio-pcre kamailio-postgres
* /etc/init.d/kamailio start
* rc-update add kamailio

* FUTURE: POST CONFIG THAT USES SUBSCRIBER TABLE FOR AUTH

= Install the SIP Media container =

== Create and Configure the container ==
{{Cmd|lxc-create -n sipmedia -f /etc/lxc/default.conf -t alpine}}
Create the startup Script
{{Cmd|ln -s /etc/init.d/lxc /etc/init.d/lxc.sipmedia}}

Edit the container's config file found at /var/lib/lxc/sipmedia/config, to reflect the network for the SIP Media container

{{cat|/var/lib/lxc/sipmedia/config|
...
lxc.network.link {{=}} bond0.1101
...
}}

Start the container
{{Cmd|/etc/init.d/lxc.sipmedia}}

Configure the container to automatically start
{{Cmd|rc-update add lxc.sipmedia}}

== Enter the SIP Media container ==
{{Cmd|lxc-console -n sipmedia}}
Login as root
{{Note|If the need arises to exit the container press {{Key| Ctrl}}+{{Key| a}} + {{Key| q}}}}
Remove obsolete /etc/network/interfaces
{{Cmd|rm /etc/network/interfaces}}
Create and configure the new /etc/network/interfaces as shown below:
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 10.2.0.5
netmask 255.255.255.0
gateway 10.2.0.1
}}

Startup networking
{{Cmd| /etc/init.d/networking start}}

Configure and enable proxy settings
{{Cmd|setup-proxy http://10.1.0.2:8080
. /etc/profile.d/proxy.sh}}

Configure remote administration
{{Cmd|apk update
setup-sshd -c openssh
sed -i "s/.PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sed -i "s/.UseDNS yes/UseDNS no/" /etc/ssh/sshd_config}}

Start ssh
{{Cmd|/etc/init.d/sshd start}}

Configure a passwd for the container
{{Cmd|passwd}}

Setup acf for web administration
{{Cmd|setup-acf}}

== Setup Firewall ==
{{Cmd|apk add acf-awall}}

With your favorite editor, create the policies for the firewall
{{cat|/etc/awall/optional/base.json|
{
"description": "Management",

"policy": [
{ "in": "_fw", "action": "accept" }
],

"filter": [
{
"out": "_fw",
"service": [ "ssh", "https", "ping" ],
"action": "accept"
}
]
}
}}
{{cat|/etc/awall/optional/sip-track.json|
{

"description": "Phone system with SIP connection tracking",

"filter": [
{
"out": "_fw",
"service": [ "sip", "sip-tls" ],
"action": "accept"
}
]

}
}}
Enable and activate firewall policies, and configure iptables to start at boot
{{Cmd|awall enable base
awall enable sip-track
awall activate -f
rc-update add iptables
}}

== Install and Configure Freeswitch ==
Install package
{{Cmd|Install Freeswitch Package}}

Configure /etc/freeswitch/freeswitch.xml
{{cat|/etc/freeswitch/freeswitch.xml|
<pre>
...
<extension name="hold_music">
<condition field="destination_number" expression="^moh$">
<action application="answer"/>
<action application="playback" data="$${hold_music}"/>
</condition>
</extension>
...
<X-PRE-PROCESS cmd="set" data="hold_music=local_stream://default"/>
...
FUTURE: ADD VOICEMAIL
</pre>
}}
Start Freeswitch and configure to start at boot
{{Cmd|/etc/init.d/freeswitch start
rc-update add freeswitch}}

= Install the WiFi Web Proxy Container =

== Create and Configure the container ==
{{Cmd|lxc-create -n wifi -f /etc/lxc/default.conf -t alpine}}
Create the startup Script
{{Cmd|ln -s /etc/init.d/lxc /etc/init.d/lxc.wifi}}

Edit the container's config file found at /var/lib/lxc/wifi/config, to reflect the network for the wifi container

{{cat|/var/lib/lxc/wifi/config|
...
lxc.network.link {{=}} bond0.701
...
}}

Start the container
{{Cmd|/etc/iniit.d/lxc.wifi}}

Configure the container to automatically start
{{Cmd|rc-update add lxc.wifi}}

== Enter the wifi container ==
{{Cmd|lxc-console -n wifi}}
Login as root
{{Note|If the need arises to exit the container press {{Key| Ctrl}}+{{Key| a}} + {{Key| q}}}}
Remove obsolete /etc/network/interfaces
{{Cmd|rm /etc/network/interfaces}}
Create and configure the new /etc/network/interfaces as shown below:
{{cat|/etc/network/interfaces|
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 172.17.48.1
netmask 255.255.255.0

auto eth1
iface eth1 inet static
address 10.1.0.254
netmask 255.255.255.252
gateway 10.1.0.253

auto eth2
iface eth2 inet static
address 10.1.0.131
netmask 255.255.255.192
}}

Startup networking
{{Cmd| /etc/init.d/networking start}}

Configure remote administration
{{Cmd|apk update
setup-sshd -c openssh
sed -i "s/.PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sed -i "s/.UseDNS yes/UseDNS no/" /etc/ssh/sshd_config}}

Start ssh
{{Cmd|/etc/init.d/sshd start}}

Configure a passwd for the container
{{Cmd|passwd}}

Setup acf for web administration
{{Cmd|setup-acf}}

== Setup Firewall ==
{{Cmd|apk add acf-awall}}
{{Todo|Need to lock down firewall rules}}

==Install and Configure the Recursive DNS Service ==
Install unbound package
{{Cmd|apk add unbound}}
With your favorite editor configure /etc/unbound/unbound.conf
{{cat|/etc/unbound/unobund.conf|
server:
verbosity: 1
interface: 172.17.48.1
do-ip4: yes
do-ip6: no
do-udp: yes
do-tcp: yes
do-daemonize: yes
access-control: 172.17.0.0/16 allow
access-control: 127.0.0.0/8 allow

do-not-query-localhost: no

root-hints: "/etc/unbound/root.hints"

python:
remote-control:
control-enable: no
}}
== Install and Configure the Proxy service ==
Install the necessary packages
{{Cmd|apk add squid squark lighttpd}}
With your preferred editor configure /etc/squid/squid.conf
{{cat|/etc/squid/squid.conf|
<pre>
#Squid config

# This port listens for client requests
http_port 172.17.48.1:8080 transparent
http_port 127.0.0.1:8081

visible_hostname wifi.local
cache_mem 8 MB
# If you don't have an HD installed comment the "cache_dir" line below
cache_dir aufs /var/cache/squid 900 16 256

# Even though we only use one proxy, this line is recommended
# More info: http://www.squid-cache.org/Versions/v2/2.7/cfgman/hierarchy_stoplist.html
hierarchy_stoplist cgi-bin ?

# Keep 7 days of access logs
logfile_rotate 7

logformat squark %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt %rG
access_log /var/log/squid/access.log squark
cache_store_log none
pid_filename /var/run/squid.pid

# Make sure client IP is passed to Squark
log_uses_indirect_client on
acl_uses_indirect_client on

# Debugging Squid, see http://wiki.squid-cache.org/KnowledgeBase/DebugSections
# for more info
# Keep 7 days of cache log
debug_options rotate=7

# Web auditors want to see the full uri, even with the query terms
strip_query_terms off

refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320

coredump_dir /var/cache/squid

dns_nameservers 172.17.48.1

#
# Authentication
#
# Squark external acl
#external_acl_type squark_snmp_auth_D children-max=1 ttl=4 grace=1 negative_ttl=0 concurrency=128 %SRC /usr/bin/squark-auth-snmp -c public -R <SWITCH_IP> -i <D_VLAN_IF> -v <D_VLAN_ID> -f "%N-%i=%I" -T /etc/squark/topology.conf

#
# Access Control Lists (ACL's)
#

# Standard ACL settings
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp
acl to_localhost dst 172.17.48.1
acl SSL_ports port 443 563 8004 9000
acl Safe_ports port 21 70 80 81 210 280 443 563 499 591 777 1024 1022 1025-65535
acl purge method PURGE
acl CONNECT method CONNECT

#acl SquarkAuth external squark_auth
#acl SquarkSnmpAuthD external squark_snmp_auth_D

# Squark filter
url_rewrite_program /usr/bin/squark-filter
url_rewrite_children 1 concurrency=128

# Require authentication
acl userlist src all

# Definition of zones
acl Zone_D src 172.17.48.0/24

#
# Access restrictions
#

cache deny QUERY

# Only allow cachemgr access from localhost
http_access allow manager localhost
http_access deny manager

# Only allow purge requests from localhost
http_access allow purge localhost
http_access deny purge

# Deny requests to unknown ports
http_access deny !Safe_ports

# Deny CONNECT to other than SSL ports
http_access deny CONNECT !SSL_ports

# Allow hosts in Zone_D to access the entire Internet
http_access allow Zone_D

# Denying all access not explictly allowed
http_access deny all

##Squark URL rewriter
#Prevent squark from filtering itself
url_rewrite_access deny manager
url_rewrite_access deny to_localhost

#Finally, permit access
url_rewrite_access allow Zone_D

http_reply_access allow all
icp_access allow all
</pre>
}}
Configure lighttpd
{{cat|/etc/lighttpd/lighttpd.conf|
<pre>
var.basedir = "/var/www/localhost"
var.logdir = "/var/log/lighttpd"
var.statedir = "/var/lib/lighttpd"

server.modules = (
"mod_access",
"mod_accesslog",
"mod_extforward"
)

include "mime-types.conf"
include "mod_cgi.conf"

server.username = "lighttpd"
server.groupname = "lighttpd"

server.document-root = var.basedir + "/squark"
server.pid-file = "/var/run/lighttpd.pid"

server.errorlog = var.logdir + "/error.log"

server.indexfiles = ("index.php", "index.html",
"index.htm", "default.htm")

server.follow-symlink = "enable"

server.port = 81
server.bind = "172.17.48.1"

static-file.exclude-extensions = (".php", ".pl", ".cgi", ".fcgi")

accesslog.filename = var.logdir + "/access.log"

url.access-deny = ("~", ".inc")

extforward.forwarder = ("172.17.48.1" => "trust")
</pre>
}}
{{cat|/etc/lighttpd/mod_cgi.conf|
<pre>
###############################################################################
# mod_cgi.conf
# include'd by lighttpd.conf.
# $Header: /var/cvsroot/gentoo-x86/www-servers/lighttpd/files/conf/mod_cgi.conf,v 1.1 2005/08/27 12:36:13 ka0ttic Exp $
###############################################################################

#
# see cgi.txt for more information on using mod_cgi
#

server.modules += ("mod_cgi")

# NOTE: this requires mod_alias
alias.url = (
"/cgi-bin/" => var.basedir + "/cgi-bin/"
)

#
# Note that you'll also want to enable the
# cgi-bin alias via mod_alias (above).
#

$HTTP["url"] =~ "^/cgi-bin/" {
# disable directory listings
dir-listing.activate = "disable"
# only allow cgi's in this directory
cgi.assign = (
".pl" => "/usr/bin/perl",
".cgi" => "/usr/bin/haserl"
)
}

# vim: set ft=conf foldmethod=marker et :
</pre>
}}
Link Squark web pages to the Web server home directory
{{Cmd|ln -s /usr/share/squark/www/ /var/www/localhost/squark}}
Make 'squid' and 'lighttpd' users member of the group squark
{{Cmd|addgroup squid squark
addgroup lighttpd squark}}
Start lighttpd and configure the Web service to start at boot
{{Cmd|/etc/init.d/lighttpd start
rc-update add lighttpd}}
Start Squid and configure it to start at boot
{{Cmd|/etc/init.d/squid start
rc-update add squid}}

[[Category:ACF]]

ISP Mail Server 2.x HowTo

2016-07-26T23:41:25Z

Ttrask: Add ACF category

== A Full Service Mail Server ==

This document describes installation process for latest Alpine Linux 2.x platform. The goal of this document is to describe how to set up postfix, dovecot, clamav, dspam, roundecube, and postfixadmin for a full-featured "ISP" level mail server. We recommend to run server at Alpine Linux version not earlier than 2.2, since release 2.2 has a lot of important fixes for bugs and security issues. (See also [[ISP_Mail_Server_HowTo|previous installation on 1.10 platform]]. There are also [[ISP Mail Server Upgrade 2.x|notes on upgrading from v1 to v2]].)

The server must provide:

* multiple virtual domains
* admins for each domain (to add/remove virtual accounts)
* quota support per domain / account
* downloading email via IMAP / IMAPS / POP3 / POP3S
* relaying email for authenticated users with TLS or SSL (Submission / SMTPS protocol)
* standard filters (virus/spam/rbl/etc)
* web mail client
* value add services

== Set up Lighttpd + PHP ==

PostfixAdmin needs php pgpsql and imap modules, so we do it in this step.

apk add lighttpd php php-pgsql php-imap

Stop and remove mini_httpd, and move ACF to lighttpd; We are setting this up to be a multi-domain virtual web server (replace host.example.com with the actual domain):

/etc/init.d/mini_httpd stop
apk del mini_httpd
mkdir -p /var/www/domains/host.example.com/www
ln -s /usr/share/acf/www /var/www/domains/host.example.com/www/acf

Edit /var/www/domains/host.example.com/www/index.html to put a simple redirection page:

<pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>host.example.com Redirector</title>
</head>
<body>
<ul>
<li><a href="/acf">ACF</a></li>
<li><a href="/postfixadmin">PostfixAdmin</a></li>
<li><a href="/roundcube">Roundcube</a></li>
</ul>
</body>
</pre>

Edit /etc/lighttpd/mod_cgi.conf to serve haserl files by adding a "" => "" cgi handler and to treat /acf/cgi-bin as a CGI directory (remove the '^'):

$HTTP["url"] =~ "/cgi-bin/" {
# disable directory listings
dir-listing.activate = "disable"
# only allow cgi's in this directory
cgi.assign = (
".pl" => "/usr/bin/perl",
".cgi" => "/usr/bin/perl",
"" => ""
)
}

Get a web certificate, and install it. You have two options: 1. If you want to use a self-signed cert, you can use the instructions found at [[Generating SSL certs with ACF]] or [[Generating SSL certs with ACF 1.9]] to generate it. 2. Use the certificate created with the '''setup-acf''' command. 3. Get certificate from trusted root certification centers.

'''Option 1:'''
If you create your own self-signed certificate, you can create the "server-bundle.pem" and the "ca-crt.pem" file with these commands:

openssl pkcs12 -nokeys -cacerts -in certificate.pfx -out /etc/lighttpd/ca-crt.pem
openssl pkcs12 -nodes -in certificate.pfx -out /etc/lighttpd/server-bundle.pem
chown root:root /etc/lighttpd/server-bundle.pem
chmod 400 /etc/lighttpd/server-bundle.pem

'''Note:''' The server certificate ''and'' key are in the server-bundle.pem file, so it is critical that the file be read-only by user "root".

'''Option 2:'''
If you prefer to just use the default certificate created with the '''setup-acf''' command, then you will need to do the following:

setup-acf

During the above process, mini_httpd will be started, if it isn't already, and a certificate will be created. Once you have completed the setup-acf steps, do the following to move the certificate files to the correct location for lighttpd to use.

mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server-bundle.pem
chown root:root /etc/lighttpd/server-bundle.pem
chmod 400 /etc/lighttpd/server-bundle.pem

'''Option 3:'''
You may decide to receive a certificate from trusted root certification centers. One good choice is to request free certificate from StartSSL at page: https://www.startssl.com/?app=33.

Add these lines to /etc/lighttpd/lighttpd.conf to point to the new document root, and set it up to listen on port 443 (replace ''host.example.com'' with the actual domain and ''ip_address_of_server'' with the actual IP address):

<pre>

simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/host.example.com/"
simple-vhost.document-root = "www/"

$SERVER["socket"] == "ip_address_of_server:443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server-bundle.pem"
}
</pre>

If you went with Option 1 above, then add an additional line underneath the ssl.pem file line, so that the section appears as follows:

$SERVER["socket"] == "ip_address_of_server:443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server-bundle.pem"
ssl.ca-file = "/etc/lighttpd/ca-crt.pem"
}

Ensure that the simple_vhosts module is loaded, as well as the cgi config scripts by uncommenting the following lines in /etc/lighttpd/lighttpd.conf:

server.modules = (
# other modules may be listed
"mod_simple_vhost",
# other modules may be listed
.
.
.
include "mod_cgi.conf"
include "mod_fastcgi.conf"

Stop and remove mini_httpd; start lighttpd, test:

/etc/init.d/mini_httpd stop
rc-update del mini_httpd
apk del mini_httpd
rc-update add lighttpd
/etc/init.d/lighttpd start

At this point you should be able to see ACF being served with lighttpd (Note: this will work well with alpine 1.10 and 2.x. With earlier versions there will be problems.) https://host.example.com/acf/

== Install Postgresql ==

Add and configure postgresql:

apk add acf-postgresql postgresql-client
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
rc-update add postgresql

At this point any user can connect to the sql server with "trust" mechanism. If you want to enforce password authentication (you probably do) edit /var/lib/postgresql/9.0/data/pg_hba.conf. Since by default "trust" mechanism is for local connections only we assume using trust password-less access as safe.

Create the postfix database:

psql -U postgres
create user postfix with password '******';
create database postfix owner postfix;
\q

(Of course, use your selected password where ******* is shown above.)

== Install PostfixAdmin ==

We are going to install the postfix admin web front-end before we install the mail server. This just creates an interface to populate the SQL tables that postfix and dovecot will use.

Download PostfixAdmin from Sourceforge. When these instructions were written, 2.3 was the current release, so (replace host.example.com with the actual domain):

wget http://downloads.sourceforge.net/project/postfixadmin/postfixadmin/postfixadmin-2.3.3/postfixadmin-2.3.3.tar.gz
tar zxvf postfixadmin-2.3.3.tar.gz
mkdir -p /var/www/domains/host.example.com/www/postfixadmin
mv postfixadmin-2.3.3/* /var/www/domains/host.example.com/www/postfixadmin
rm -rf postfixadmin*

Edit /var/www/domains/host.example.com/www/postfixadmin/config.inc.php and modify at least these lines (replace host.example.com with the actual domain):

$CONF['configured'] = true;
$CONF['setup_password'] = ""; << Don't change this yet
$CONF['database_type'] = 'pgsql';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfix';
$CONF['database_password'] = '*****'; << The password you chose above
$CONF['database_name'] = 'postfix';
$CONF['database_prefix'] = "";
$CONF['admin_email'] = 'you@some.email.com'; << Your email address
$CONF['encrypt'] = 'md5crypt';
$CONF['authlib_default_flavor'] = 'md5raw';
$CONF['dovecotpw'] = "/usr/sbin/dovecotpw";
$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
$CONF['aliases'] = '10';
$CONF['mailboxes'] = '10';
$CONF['maxquota'] = '10';
$CONF['quota'] = 'YES';
$CONF['quota_multiplier'] = '1024000';
$CONF['vacation'] = 'NO';
$CONF['vacation_control'] ='NO';
$CONF['vacation_control_admin'] = 'NO';
$CONF['alias_control'] = 'YES';
$CONF['alias_control_admin'] = 'YES';
$CONF['special_alias_control'] = 'YES';
$CONF['fetchmail'] = 'NO';
$CONF['user_footer_link'] = "http://host.example.com/postfixadmin";
$CONF['footer_link'] = 'http://host.example.com/postfixadmin/main.php';
$CONF['create_mailbox_subdirs_prefix']="";
$CONF['used_quotas'] = 'YES';
$CONF['new_quota_table'] = 'YES';

You should further edit /var/www/domains/host.example.com/www/postfixadmin/config.inc.php and replace all instances of "change-this-to-your.domain.tld" with your actual mail domain. This can be done with busybox sed (replace example.com with your domain name):

sed -i -e 's/change-this-to-your.domain.tld/example.com/g' /var/www/domains/host.example.com/www/postfixadmin/config.inc.php

Go to https://host.example.com/postfixadmin/setup.php

Create the password hash, add it to the config.inc.php file

Go back to https://host.example.com/postfixadmin/setup.php

Create superadmin account.

'''NOTE:''' Check http://sourceforge.net/tracker/index.php?func=detail&aid=2859165&group_id=191583&atid=937964 if you have bug on listing domains page.

== Install Postfix ==

Create a user for the virtual mail delivery, and get its uid/gid (you'll need the numeric uid/gid for postfix):

adduser vmail -H -D -s /bin/false
grep vmail /etc/passwd

(In examples below, we use 1006/1006 for the uid/gid)

Create the mail directory, and assign vmail as the owner:

mkdir -p /var/mail/domains
chown -R vmail:vmail /var/mail/domains

Install postfix:

apk add acf-postfix postfix-pgsql postfix-pcre

Edit the /etc/postfix/main.cf file. Here's an example (don't forget to replace the uid/gid):

myhostname=host.example.com
mydomain=example.com

mydestination = localhost.$mydomain, localhost
mynetworks_style = subnet
mynetworks = 127.0.0.0/8

virtual_mailbox_domains = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_domains_maps.cf
virtual_alias_maps = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_catchall_maps.cf

virtual_mailbox_maps = proxy:pgsql:/etc/postfix/sql/pgsql_virtual_mailbox_maps.cf,
proxy:pgsql:/etc/postfix/sql/pgsql_virtual_alias_domain_mailbox_maps.cf

virtual_mailbox_base = /var/mail/domains/
virtual_gid_maps = static:1006
virtual_uid_maps = static:1006
virtual_minimum_uid = 100
virtual_transport = virtual

# This next command means you must create a virtual
# domain for the host itself - ALL mail goes through
# The virtual transport

mailbox_transport = virtual
local_transport = virtual
local_transport_maps = $virtual_mailbox_maps

smtpd_helo_required = yes
disable_vrfy_command = yes
message_size_limit = 10240000
queue_minfree = 51200000

smtpd_sender_restrictions =
permit_mynetworks,
reject_non_fqdn_sender,
reject_unknown_sender_domain

smtpd_recipient_restrictions =
reject_non_fqdn_recipient,
reject_unknown_recipient_domain,
permit_mynetworks,
permit_sasl_authenticated,
reject_unauth_destination,
reject_rbl_client dnsbl.sorbs.net,
reject_rbl_client zen.spamhaus.org,
reject_rbl_client bl.spamcop.net

smtpd_data_restrictions = reject_unauth_pipelining

# we will use this later - This prevents cleartext authentication
# for relaying
smtpd_tls_auth_only = yes

Now we need to create a *bunch* of files so that postfix can get the delivery information out of sql. Here's a shell script to create the scripts. Change PGPW to the password for the postfix user of the postfix SQL database:

cd /etc/postfix
mkdir sql
PGPW="ChangeMe"

cat - <<EOF >sql/pgsql_virtual_alias_domain_catchall_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select goto From alias,alias_domain where alias_domain.alias_domain = '%d' and alias.address = '@' || alias_domain.target_domain and alias.active = true and alias_domain.active= true
EOF

cat - <<EOF >sql/pgsql_virtual_alias_domain_mailbox_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select maildir from mailbox,alias_domain where alias_domain.alias_domain = '%d' and mailbox.username = '%u' || '@' || alias_domain.target_domain and mailbox.active = true and alias_domain.active
EOF

cat - <<EOF >sql/pgsql_virtual_alias_domain_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = select goto from alias,alias_domain where alias_domain.alias_domain='%d' and alias.address = '%u' || '@' || alias_domain.target_domain and alias.active= true and alias_domain.active= true
EOF

cat - <<EOF >sql/pgsql_virtual_alias_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select goto From alias Where address='%s' and active ='1'
EOF

cat - <<EOF >sql/pgsql_virtual_domains_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select domain from domain where domain='%s' and active='1'
EOF

cat - <<EOF >sql/pgsql_virtual_mailbox_maps.cf
user=postfix
password = $PGPW
hosts = localhost
dbname = postfix
query = Select maildir from mailbox where username='%s' and active=true
EOF

chown -R postfix:postfix sql
chmod 640 sql/*

At this point you should be able to start up postfix:

newaliases # so postfix is happy...
/etc/init.d/postfix start
rc-update add postfix

=== Create a domain in PostfixAdmin and test ===

Go to http://host.example.com/postfixadmin/

Log in using the superadmin account, create a domain for the local box (e.g. example.com), and create a user mailbox (e.g. root).

From the machine, send a test message:

sendmail -t root@example.com
subject: test
.
^d

In /var/log/mail.log (or /var/log/messages, if you still have busybox syslogd running) you should see the message queued. The message should be in /var/mail/domains/example.com/root/new

== Install Dovecot ==

Dovecot is the POP3/IMAP server to retrieve mail.

As before, we install dovecot:

apk add acf-dovecot dovecot-pgsql

Edit /etc/dovecot/dovecot.conf:

<pre>
auth_mechanisms = plain login
auth_username_format = %Lu
#auth_verbose = yes
#auth_debug = yes
#auth_debug_passwords = no

disable_plaintext_auth = no

mail_location = maildir:/var/mail/domains/%d/%n

first_valid_gid = 1000
first_valid_uid = 1000
last_valid_gid = 65535
last_valid_uid = 65535

log_timestamp = "%Y-%m-%d %H:%M:%S "
login_greeting = IMAP server ready

protocols = imap

service anvil {
client_limit = 2100
}

ssl_cert = </etc/lighttpd/server-bundle.pem
ssl_key = </etc/lighttpd/server-bundle.pem

userdb {
args = uid=1006 gid=1006 home=/var/mail/domains/%d/%n
driver = static
}

passdb {
args = /etc/dovecot/dovecot-sql.conf
driver = sql
}

protocol imap {
mail_plugins = autocreate
}

plugin {
autocreate = Trash
autocreate2 = Spam
autocreate3 = Sent
autosubscribe = Trash
autosubscribe2 = Spam
autosubscribe3 = Sent
}
</pre>

Be sure to replace the uid and gid with the appropriate values for the vmail user.

We need a certificate for SSL/TLS authentication, so in the example above, we use the lighttpd cert. That way when the cert is renewed/replaced, Dovecot will have access to the new cert as well.

Create the /etc/dovecot/dovecot-sql.conf file:

driver = pgsql
connect = host=localhost dbname=postfix user=postfix password=********
password_query = select username,password from mailbox where local_part = '%n' and domain = '%d'
default_pass_scheme = MD5-CRYPT

Again, change the password above to your postfix user password, and protect the file from prying eyes:

chown root:root /etc/dovecot/dovecot-sql.conf
chmod 600 /etc/dovecot/dovecot-sql.conf

Start dovecot
/etc/init.d/dovecot start
rc-update add dovecot

== Testing ==

Make sure your firewall allows in ports 25(SMTP) 110 (POP3), 995 (POP3S), 143(IMAP), 993(IMAPS), or whatever subset you support.

At this point, you should be able to:
* Create a new domain and add users with PostfixAdmin
* Send mail to those users via SMTP to port 25
* Retrieve mail using the user's full email and password (e.g. username: user@example.com password: ChangeMe)

== Value Add Features ==

If you followed the guide above, you now have a functional mail server with many interconnected parts. The features below assume that the server is already running as described above. You should be able to add any or all of these features below to further enhance the mail service.

=== Virus Scanning ===

This procedure uses clamav and the postfix content_filter mechanism to scan inbound and outbound email for viruses. Infected emails are dropped. Clean emails are tagged with a "scanned by clamav" header.

* Install clamav and clamsmtp:
apk add acf-clamav clamsmtp
* Edit the /etc/clamav/clamd.conf file if desired (not necessary in most cases)
* Edit /etc/clamsmtpd.conf and verify the following lines
OutAddress: 10026
Listen: 127.0.0.1:10025
Header: X-Virus-Scanned: ClamAV using ClamSMTP
Action: drop
User: clamav
* Start the daemons
rc-update add clamd
rc-update add clamsmtpd
/etc/init.d/clamd start
/etc/init.d/clamsmtpd start
* Verify clamsmtp is listening on port 10025:
netstat -anp | grep clamsmtp
* [http://memberwebs.com/stef/software/clamsmtp/postfix.html Following the clamsmtp instructions]
** edit /etc/postfix/main.cf and add:
content_filter = scan:[127.0.0.1]:10025
** edit /etc/postfix/master.cf and add
# AV scan filter (used by content_filter)
scan unix - - n - 16 smtp
-o smtp_send_xforward_command=yes
-o smtp_enforce_tls=no
# For injecting mail back into postfix from the filter
127.0.0.1:10026 inet n - n - 16 smtpd
-o content_filter=
-o receive_override_options=no_unknown_recipient_checks,no_header_body_checks
-o smtpd_helo_restrictions=
-o smtpd_client_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks_style=host
-o smtpd_authorized_xforward_hosts=127.0.0.0/8
* postfix reload
* Send and email into a local virtual domain - it should have the ''X-Virus-Scanned: ClamAV using ClamSMTP'' header.

=== Relay for Authenticated Users ===

As configured above, the mail server accepts email from the Internet, but it does not relay email. If it is a perimeter exchanger for a protected network, then you can add the protected networks to the ''mynetworks'' configuration line in /etc/postfix/main.cf

This configuration change allows ''remote'' users to authenticate against the mail server and relay through it. The rules for relaying are:
* Only authenticated users can relay
* Authentication Credentials must be encrypted with TLS or SSL
* Allow Submission and SMTPS ports for relaying (many consumer networks block port 25 - SMTP by default)
The process uses the dovecot authentication mechanism (used with IMAPS) to authenticate users before they are allowed to relay through postfix.

* Edit /etc/dovecot/dovecot.conf and add the following:
# this is for postfix SASL (authenticated users can relay through us)

service auth {
unix_listener /var/spool/postfix/private/auth {
group = postfix
mode = 0660
user = postfix
}
unix_listener /var/spool/postfix/auth-master {
group = postfix
mode = 0660
user = vmail
}
user = root
}

* Restart dovecot
/etc/init.d/dovecot restart
* Edit /etc/postfix/main.cf and add:
# TLS Stuff -- since we allow SASL with tls *only*, we have to set up TLS first

smtpd_tls_cert_file = /etc/lighttpd/server-bundle.pem
smtpd_tls_key_file = /etc/lighttpd/server-bundle.pem
smtpd_tls_CAfile = /etc/lighttpd/ca-crt.pem
# If tls_security_level is set to "encrypt", then SMTP rejects
# unencrypted email (e.g. normal mail) which is bad.
# By setting it to "may" you get TLS encrypted mail from google, slashdot, and other
# interesting places. Check your logs to see who
smtpd_tls_security_level = may
# Log info about the negotiated encryption levels
smtpd_tls_received_header = yes
smtpd_tls_loglevel = 1

# SASL - this allows senders to authenticiate themselves
# This along with "permit_sasl_authenticated" in smtpd_recipient_restrictions allows relaying
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
smtpd_sasl_authenticated_header = yes
broken_sasl_auth_clients = yes
smtpd_tls_auth_only = yes
* Edit /etc/postfix/master.cf and enable the submission and smtps transports. They are probably already at the top of your master.cf file, just commented out:
submission inet n - n - - smtpd
-o smtpd_tls_security_level=encrypt
-o smtpd_sasl_auth_enable=yes
-o smtpd_client_restrictions=permit_sasl_authenticated,reject
-o milter_macro_daemon_name=ORIGINATING
smtps inet n - n - - smtpd
-o smtpd_tls_security_level=encrypt
-o smtpd_tls_wrappermode=yes
-o smtpd_sasl_auth_enable=yes
-o smtpd_client_restrictions=permit_sasl_authenticated,reject
-o milter_macro_daemon_name=ORIGINATING
*Verfiy submission and smtps are defined in /etc/services
grep "submission\|ssmtp" /etc/services
submission 587/tcp # mail message submission
submission 587/udp
smtps 465/tcp ssmtp # smtp protocol over TLS/SSL
smtps 465/udp ssmtp
* Restart postfix
postfix reload

At this point, you should be able to set up a mail client to relay through the server with TLS (port 587) or SSL (port 465) Note that "plain" authentication is used because the underlying link is encrypted. For example, in Thunderbird leave "secure authentication" unchecked, and choose STARTTLS (or TLS) for the connection security.

=== Mailbox Quotas ===

In the default configuration, PostfixAdmin knows about quotas, but they are not enforced. Documentation on the web mentions the [http://vda.sourceforge.net vda patch to postfix] to enforce quotas. The only bad thing... its a ''patch''. Postfix and Dovecot are both conservative systems, so if the patch isn't in the upstream source, we'll assume there's a good reason. There is a way of using quotas without patches - and it involves using dovecot's [http://wiki2.dovecot.org/LDA deliver] lda for local delivery.

* Replace /etc/dovecot/dovecot.conf with the following:

<pre>
auth_mechanisms = plain login
auth_username_format = %Lu
#auth_verbose = yes
#auth_debug = yes
#auth_debug_passwords = no

disable_plaintext_auth = no

info_log_path = /var/log/dovecot-info.log
log_path = /var/log/dovecot.log

mail_location = maildir:/var/mail/domains/%d/%n

first_valid_gid = 1000
first_valid_uid = 1000
last_valid_gid = 65535
last_valid_uid = 65535

log_timestamp = "%Y-%m-%d %H:%M:%S "
login_greeting = IMAP server ready

protocols = imap

service anvil {
client_limit = 2100
}

service auth {
unix_listener /var/spool/postfix/auth-master {
group = postfix
mode = 0660
user = vmail
}
unix_listener /var/spool/postfix/private/auth {
group = postfix
mode = 0660
user = postfix
}
user = root
}

service imap-login {
inet_listener imap {
address = 127.0.0.1
port = 143
}
inet_listener imaps {
address = *
port = 993
}
process_limit = 1024
}

service pop3-login {
process_limit = 1024
}

service dict {
unix_listener dict {
group =
mode = 0600
user = vmail
}
}

ssl_ca = </etc/ssl/certs/<CA Certificate file>
ssl_cert = </etc/ssl/private/<Public part of certificate file>
ssl_key = </etc/ssl/private/<Private part of certificate file>

passdb {
args = /etc/dovecot/dovecot-pgsql.conf
driver = sql
}

userdb {
driver = prefetch
}

userdb {
args = /etc/dovecot/dovecot-pgsql.conf
driver = sql
}

plugin {
quota = dict:user::proxy::quotadict

autocreate = Trash
autocreate2 = Spam
autocreate3 = Sent
autosubscribe = Trash
autosubscribe2 = Spam
autosubscribe3 = Sent
}

protocol imap {
mail_plugins = autocreate quota imap_quota
}

protocol pop3 {
mail_plugins = quota
}

dict {
quotadict = pgsql:/etc/dovecot/dovecot-dict-quota.conf
}

protocol lda {
auth_socket_path = /var/spool/postfix/auth-master
mail_plugins = quota
postmaster_address = postmaster@host.example.com
sendmail_path = /usr/sbin/sendmail
}
</pre>

* edit <tt>/etc/dovecot/dovecot-sql.conf</tt> and replace the user and password queries with the following (you may not have a user_query yet - add it):

password_query = select username as user, password, 1006 as userdb_uid, 1006 as userdb_gid, '*:bytes=' || quota as userdb_quota_rule from mailbox where local_part = '%n' and domain = '%d'
user_query = select '/var/mail/domains/' || maildir as home, 1006 as uid, 1006 as gid, '*:bytes=' || quota as quota_rule from mailbox where local_part = '%n' and domain ='%d'

* create <tt>/etc/dovecot/dovecot-dict-quota.conf</tt>
connect = host=localhost dbname=postfix user=postfix password=********

map {
pattern = priv/quota/storage
table = quota2
username_field =username
value_field = bytes
}

map {
pattern= priv/quota/messages
table = quota2
username_field = username
value_field = messages
}

Again, change the password above to your postfix user password, and protect the file from prying eyes:
chown dovecot:root /etc/dovecot/dovecot-sql.conf
chmod 600 /etc/dovecot/dovecot-sql.conf
chown dovecot:root /etc/dovecot/dovecot-dict-quota.conf
chmod 600 /etc/dovecot/dovecot-dict-quota.conf

Side note: [http://wiki2.dovecot.org/Quota/Dict The Dovecot Quota Documentation] mentions the need for a trigger with pgsql. This was created in the PostfixAdmin install, which is why you instantiated the pgsql language when creating the database. If not, you will need to create the trigger, to reference the quota2 table, not the quota table mentioned in the dovecot docs.

* create a new transport for the dovecot lda. Add the following to /etc/postfix/master.cf:
# The dovecot deliver lda
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/libexec/dovecot/deliver -f ${sender} -d ${user}@${nexthop}

* Edit the /etc/postfix/main.cf. Replace
virtual_transport = virtual
with
virtual_transport = dovecot
dovecot_destination_recipient_limit = 1

Change permissions on the /var/log/dovecot* log files, so that the vmail user can write to them:

chown vmail:vmail /var/log/dovecot*

Restart Postfix and Dovecot:

/etc/init.d/postfix restart
/etc/init.d/dovecot restart

'''TODO''' This will cause over-quota emails to bounce. Which could be a source of backscatter. We need a way of checking quota limits after RBL checking but before the message is accepted in the queue.

=== WebMail (RoundCube) ===

[http://roundcube.net/ RoundCube] is an "ajax /Web2.0" web-mail client. These instructions are for the Alpine Linux 2.2 repository

* Verify that you have at least the following in /etc/postfix/main.cf. Unless you have followed the Relay for Authenticated Users section above, set '''smtpd_tls_auth_only = no''', otherwise leave it set to '''yes''':

<pre>
# SASL - this allows senders to authenticiate themselves
# This along with "permit_sasl_authenticated" in smtpd_recipient_restrictions allows relaying
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/dovecot-auth.sock
smtpd_sasl_auth_enable = yes
smtpd_sasl_authenticated_header = yes
# Set the next line to no if TLS auth is not configured
smtpd_tls_auth_only = no
</pre>

* Ensure you have followed section ''Relay_for_Authenticated_Users''.

* Restart the relevant services:

<pre>
/etc/init.d/postfix restart
/etc/init.d/dovecot restart
</pre>

* Add the package and related php modules:

apk add roundcubemail php-xml php-openssl php-mcrypt php-gd php-iconv php-dom php-intl

* Link the roundcube application back into the docroot

ln -s /usr/share/webapps/roundcube /var/www/domains/host.example.com/www/roundcube

* Install ''roundcubemail-install'' package

apk add roundcubemail-installer

* Follow the instructions in /usr/share/webapps/roundcube/INSTALL:
cd /usr/share/webapps/roundcube
chown -R lighttpd:lighttpd /var/log/roundcube

su postgres
createuser roundcube
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) y
createdb -O roundcube -E UNICODE -T template0 roundcubemail
psql roundcubemail
roundcubemail=# ALTER USER roundcube WITH PASSWORD 'the_new_password';
roundcubemail=# \c - roundcube
roundcubemail=> \i /usr/share/webapps/roundcube/SQL/postgres.initial.sql
roundcubemail=> \q
exit

* Edit /etc/php/php.ini and set date.timezone to your local timezone, or to UTC

* Restart lighttpd to verify the new php libraries are used

/etc/init.d/lighttpd restart

* Enable installer mode in /etc/roundcube/main.inc.php file:

$rcmail_config['enable_installer'] = true;

* Point your browser to https://host.example.com/roundcube/installer
* Start installation

For the specific configuration parameters in the install step:

{| class="wikitable"
!Property
!Setting
|-
| ''enable_spellcheck'' || disabled
|-
| ''identities_level'' || one identity with possibility to edit all params but not email address
|-
| ''log driver'' || syslog
|-
| ''sylog_id'' || roundcube
|-
| ''syslog_facility'' || mailsubsystem
|-
| ''db_dnsw'' || pgsql properties, as described above
|-
| ''imap_host'' || 127.0.0.1
|-
| ''auto_create_user'' || enabled
|-
| ''smtp_server'' || 127.0.0.1
|-
| ''smtp_port'' || 25
|-
| ''smtp_user/smtp_pass'' || enable ''Use Current IMAP username and password for SMTP authentication''
|-
| ''smtp_log'' || enable (optional, but gives additional log record)
|}

The other items can be left at default settings, or adjusted if desired.

* Follow the instructions in step 2 of the install to copy the files to the server
* You should now be able to get to roundcube at https://host.example.com/roundcube

* After its working, the INSTALL file recommends removing the install directory.

apk del roundcubemail-installer

* Disable installer mode in /etc/roundcube/main.inc.php file:

$rcmail_config['enable_installer'] = false;

* Change the ownership and permissions

cd /usr/share/webapps/roundcube
chown -R root:root LICENSE UPGRADING INSTALL README CHANGELOG
chmod -R 600 LICENSE UPGRADING INSTALL README CHANGELOG

* If needed customize logos such as '''watermark.gif''', '''roundcube_logo.gif''', '''favicon.ico'''

* If you would like to disable displaying of standard logos update template files accordingly

* Comment all entries like '''<div ... img src="/images/roundcube_logo.png"...''' in files:

includes/header.html
templates/error.html
templates/messageprint.html
templates/login.html
templates/printmessage.html

* Comment all entries like '''<img src="/images/watermark.gif"...''' in files:

templates/identities.html
templates/messageerror.html
watermark.html

==== Enable Plug-ins ====

RoundCube has various useful plug-ins, which could be found in ''/usr/share/webapps/roundcube/plugins'' directory. For example you may want to enable ''password'' plug-in to let users change their passwords directly from RoundCube using an extra Password Tab added to User Settings.

* Grant limited permissions for ''roundcube'' database role
psql -U postgres postfix
postfix=# GRANT UPDATE (password,modified) ON mailbox TO roundcube;
postfix=# GRANT SELECT (username) ON mailbox TO roundcube;
postfix=# GRANT INSERT ON log TO roundcube;
postfix=# \q

* Setup ''password'' plug-in parameters in ''/usr/share/webapps/roundcube/plugins/password/config.inc.php''
mv /usr/share/webapps/roundcube/plugins/password/config.inc.php.dist /usr/share/webapps/roundcube/plugins/password/config.inc.php
vi /usr/share/webapps/roundcube/plugins/password/config.inc.php

<pre>
$rcmail_config['password_minimum_length'] = 7;
$rcmail_config['password_require_nonalpha'] = true;
...
$rcmail_config['password_db_dsn'] = 'pgsql://roundcube:<roundcube_password>@localhost/postfix';
...
$rcmail_config['password_query'] = "UPDATE mailbox set password = %c, modified = NOW() where username = %u; INSERT INTO log (timestamp,username,domain,action,data) VALUES (NOW(),%u || ' (' || %h || ')',%d,'edit_password',%u)";
</pre>

* Enable ''password'' plug-in
vi /usr/share/webapps/roundcube/config/main.inc.php

<pre>
...
$rcmail_config['plugins'] = array('password');
</pre>

* Enable ''create_default_folders'' for RoundCube
vi /usr/share/webapps/roundcube/config/main.inc.php

<pre>
...
$rcmail_config['create_default_folders'] = TRUE;
...
</pre>

=== OpenLDAP based Address Book ===

This OpenLDAP configuration uses the SQL backend, which represents information stored in PostgreSQL as an LDAP subtree for Address Book functionality for email lookups, user authentication or even replication account information between sites. This procedure uses some metainformation to translate LDAP queries to SQL queries, leaving relational schema untouched, which allows SQL and LDAP applications to inter-operate without replication, and exchange data as needed. The SQL backend uses UnixODBC to connect to PostgresSQL.

* Install OpenLDAP and ODBC

<pre>
apk add openldap libldap openldap-back-sql php-ldap unixodbc psqlodbc ca-certificates
</pre>

* Update "postfix" database (it will add 'id' columns to mailbox and domain tables, also will create tables and views to represent LDAP metainformation)

'''Note''': These instructions are for example domain example.com. So make sure you replaced all entries of 'example' and 'com' according to your domain name parts.

Put the following into a new file called '''script''':

<pre>
ALTER TABLE domain ADD COLUMN id SERIAL;
ALTER TABLE mailbox ADD COLUMN id SERIAL;

CREATE TABLE ldap_entry_objclasses (
entry_id integer NOT NULL,
oc_name character varying(64)
);

CREATE TABLE ldap_oc_mappings (
name character varying(64) NOT NULL,
keytbl character varying(64) NOT NULL,
keycol character varying(64) NOT NULL,
create_proc character varying(255),
delete_proc character varying(255),
expect_return integer NOT NULL
);

ALTER TABLE ldap_oc_mappings ADD COLUMN id SERIAL;
ALTER TABLE ldap_oc_mappings ADD PRIMARY KEY (id);

CREATE TABLE ldap_attr_mappings (
oc_map_id integer NOT NULL REFERENCES ldap_oc_mappings(id),
name character varying(255) NOT NULL,
sel_expr character varying(255) NOT NULL,
sel_expr_u character varying(255),
from_tbls character varying(255) NOT NULL,
join_where character varying(255),
add_proc character varying(255),
delete_proc character varying(255),
param_order integer NOT NULL,
expect_return integer NOT NULL
);

ALTER TABLE ldap_attr_mappings ADD COLUMN id SERIAL;
ALTER TABLE ldap_attr_mappings ADD PRIMARY KEY (id);

CREATE VIEW ldap_dcs AS
((SELECT (domain.id + 100000) AS id,
('dc='::text || replace((domain.domain)::text, '.'::text, ',dc='::text)) AS dn,
1 AS oc_map_id,
100000 AS parent,
0 AS keyval,
domain.domain
FROM domain
WHERE domain.domain <> 'ALL')
UNION
(SELECT 100000 AS id,
('dc=' || regexp_replace((domain.domain)::text, '.*\\.', ''::text)) AS dn,
1 AS oc_map_id,
0 AS parent,
0 AS keyval,
(regexp_replace((domain.domain)::text, '.*\\.', ''::text)) AS domain
FROM domain
WHERE domain.domain <> 'ALL'
LIMIT 1));

CREATE VIEW ldap_entries AS
SELECT mailbox.id,
((('cn='::text || initcap(replace(split_part((mailbox.username)::text, '@'::text, 1), '.'::text, ' '::text))) || ',dc='::text) ||
replace(regexp_replace((mailbox.username)::text, '.*@', ''::text), '.'::text, ',dc='::text)) AS dn,
1 AS oc_map_id,
(SELECT ldap_dcs.id
FROM ldap_dcs
WHERE ((ldap_dcs.domain)::text = (mailbox.domain)::text)) AS parent,
mailbox.id AS keyval
FROM mailbox
UNION
SELECT ldap_dcs.id,
ldap_dcs.dn,
ldap_dcs.oc_map_id,
ldap_dcs.parent,
ldap_dcs.keyval
FROM ldap_dcs;
</pre>
'''''Question to experts: Is this normal to have in this script "WARNING: nonstandard use of \\ in a string literal"?'''''

Finally, execute the commands in the file with:
cat script | psql -U postfix postfix
rm script

* Fill out LDAP tables according to following example (make sure to separate values with TABs):

Put the following into a new file called '''script''':

<pre>
COPY ldap_oc_mappings (id, name, keytbl, keycol, create_proc, delete_proc, expect_return) FROM stdin;
1 exampleBox mailbox id \N \N 1
\.
COPY ldap_attr_mappings (id, oc_map_id, name, sel_expr, sel_expr_u, from_tbls, join_where, add_proc, delete_proc, param_order, expect_return) FROM stdin;
1 1 displayName mailbox.name \N mailbox \N \N \N 3 0
2 1 mail mailbox.username \N mailbox \N \N \N 3 0
3 1 cn mailbox.name \N mailbox \N \N \N 3 0
4 1 userPassword '{CRYPT}'||mailbox.password \N mailbox \N \N \N 3 0
\.
</pre>

Finally, execute the commands in the file with:
cat script | psql -U postfix postfix
rm script

* Check that "ldap_dcs" view looks something like this:

<pre>
echo 'select * from ldap_dcs' | psql -U postgres postfix
</pre>

<pre>
id | dn | oc_map_id | parent | keyval | domain
--------+-----------------------------+-----------+--------+--------+--------------------
100000 | dc=com | 1 | 0 | 0 | com
100001 | dc=example,dc=com | 1 | 100000 | 0 | example.com
</pre>

* Check that "ldap_entries" view looks something like this:

<pre>
echo 'select * from ldap_entries' | psql -U postgres postfix
</pre>

<pre>
id | dn | oc_map_id | parent | keyval
--------+-------------------------------------------------------+-----------+--------+--------
1 | cn=address1,dc=example,dc=com | 1 | 100001 | 1
...
123 | cn=address123,dc=example,dc=com | 1 | 100001 | 1
100000 | dc=com | 1 | 0 | 0
100001 | dc=example,dc=com | 1 | 100000 | 0
</pre>

* Configure ODBC parameters

Edit /etc/odbc.ini:

<pre>
[PostgreSQL]
Description = Connection to Postgres
Driver = PostgreSQL
Trace = Yes
TraceFile = sql.log
Database = postfix
Servername = 127.0.0.1
UserName =
Password =
Port = 5432
Protocol = 6.4
ReadOnly = No
RowVersining = No
ShowSystemTables = No
ShowOidColumn = No
FakeOidIndex = No
ConnSettings =
</pre>

Edit /etc/odbcinst.ini:

<pre>
[PostgreSQL]
Description = PostgreSQL driver for Linux
Driver = /usr/lib/psqlodbcw.so
Setup = /usr/lib/libodbcpsqlS.so
FileUsage = 1
</pre>

* Test ODBC connection

<pre>
echo "select * from domain;" | isql PostgreSQL postgres
</pre>

* Provide permission to certificate for LDAP server

<pre>
chown ldap /etc/lighttpd/server-bundle.pem
</pre>

* Edit LDAP schema

Edit /etc/openldap/schema/example.com.schema:

<pre>
attributetype ( 0.9.2342.19200300.100.1.3
NAME ( 'mail' 'rfc822Mailbox' )
DESC 'RFC1274: RFC822 Mailbox'
EQUALITY caseIgnoreIA5Match
SUBSTR caseIgnoreIA5SubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} )

attributetype ( 2.16.840.1.113730.3.1.241
NAME 'displayName'
DESC 'RFC2798: preferred name to be used when displaying entries'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )

objectclass ( 2.16.840.1.113730.3.2.2
NAME 'exampleBox'
DESC 'example.com mailbox'
MUST ( displayName $ mail $ userPassword )
)

# RFC 1274 + RFC 2247
attributetype ( 0.9.2342.19200300.100.1.25
NAME ( 'dc' 'domainComponent' )
DESC 'RFC1274/2247: domain component'
EQUALITY caseIgnoreIA5Match
SUBSTR caseIgnoreIA5SubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE )

attributetype ( 2.5.4.46 NAME 'dnQualifier'
DESC 'RFC2256: DN qualifier'
EQUALITY caseIgnoreMatch
ORDERING caseIgnoreOrderingMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
</pre>

* Configure LDAP server

Edit /etc/openldap/slapd.conf:

<pre>
include /etc/openldap/schema/example.com.schema
pidfile /var/run/openldap/slapd.pid
argsfile /var/run/openldap/slapd.args

# Uncomment next five TLS... lines if you want to use LDAPs (secured). Probably you don't want it...
#TLSCipherSuite HIGH
#TLSCACertificateFile /etc/lighttpd/ca-crt.pem
#TLSCertificateFile /etc/lighttpd/server-bundle.pem
#TLSCertificateKeyFile /etc/lighttpd/server-bundle.pem
#TLSVerifyClient never

# This is needed for proper representation of MD5-CRYPT format stored in database
# see more details in http://strugglers.net/~andy/blog/2010/01/23/openldap-and-md5crypt/
password-hash {CRYPT}
password-crypt-salt-format "$1$%.8s"

loglevel stats
moduleload /usr/lib/openldap/back_sql.so
sizelimit 3000

database sql

dbname PostgreSQL
dbuser postfix
dbpasswd *****

suffix "dc=example,dc=com"

upper_func "upper"
strcast_func "text"
concat_pattern "?||?"
has_ldapinfo_dn_ru no
lastmod off

access to attrs=userPassword by * auth

access to * by peername.ip=127.0.0.1 read
# by peername.ip=<IP>%<netmask> read
# by peername.ip=<IP> read
by users read
</pre>

* Set permissions for slapd.conf

<pre>
chown ldap:ldap /etc/openldap/slapd.conf
</pre>

* Configure startup parameters to make sure that LDAP server start AFTER PostgreSQL and listens on localhost with clear text and public IP with SSL. In case you uncommented TLS lines in slapd.conf use this string: OPTS="-h 'ldaps:// ldap://'"

Edit /etc/conf.d/slapd:

<pre>
rc_need="postgresql"
OPTS="-h 'ldap://'"
</pre>

* Start LDAP server

<pre>
rc-update add slapd default
/etc/init.d/slapd start
</pre>

* Configure LDAP client utilities. In case you uncommented TLS lines in slapd.conf replace ldap with ldaps

Edit /etc/openldap/ldap.conf

<pre>
BASE dc=example,dc=com
URI ldap://host.example.com

# Uncomment next three TLS... lines if you want to use LDAPs (secured). Probably you don't want it...
#TLS_CACERT /etc/lighttpd/ca-crt.pem
#TLS_CERT /etc/lighttpd/server-bundle.pem
#TLS_KEY /etc/lighttpd/server-bundle.pem
</pre>

* Test LDAP server

<pre>
ldapsearch -z 3
ldapsearch -z 3 -x -W -D cn=admin,dc=example,dc=com
ldapsearch -z 3 -x -W -D cn=address1,dc=example,dc=com
</pre>

* Configure RoundCube webmail for email lookups

In order to enable php-ldap support you need to restart lighttpd server

/etc/init.d/lighttpd restart

Edit /etc/roundcube/main.inc.php:

<pre>
$rcmail_config['ldap_debug'] = false;
...
$rcmail_config['address_book_type'] = 'sql';

$rcmail_config['ldap_public']['example.com'] = array(
'name' => 'example.com',
'hosts' => array('127.0.0.1'),
'port' => 389,
'use_tls' => false,
'user_specific' => false,
'base_dn' => 'dc=example,dc=com',
'bind_dn' => '',
'bind_pass' => '',
'writable' => false,
'LDAP_Object_Classes' => array("top", "exampleBox"),
'required_fields' => array("cn", "sn", "mail"),
'LDAP_rdn' => 'mail',
'ldap_version' => 3,
'search_fields' => array('mail', 'cn', 'sn', 'givenName'),
'name_field' => 'cn',
'email_field' => 'mail',
'surname_field' => 'sn',
'firstname_field' => 'gn',
'sort' => 'cn',
'scope' => 'sub',
'filter' => '(objectClass=*)', // Construct here any filter you need
'fuzzy_search' => true);

$rcmail_config['autocomplete_addressbooks'] = array('sql','example.com');
</pre>

* Fix PostfixAdmin to work with the new table definition

Edit /var/www/domains/example.com/www/postfixadmin/list-domain.php. Replace the line:
<pre>
SELECT domain.* , COUNT( DISTINCT mailbox.username ) AS mailbox_count
</pre>
With the lines:
<pre>
SELECT domain.domain, domain.description, domain.aliases, domain.mailboxes,
domain.maxquota, domain.quota, domain.transport, domain.backupmx, domain.created,
domain.modified, domain.active, COUNT( DISTINCT mailbox.username ) AS mailbox_count
</pre>

== log rotation ==

Ensure the busybox cron service is started and is configured to auto-start:

/etc/init.d/cron start
rc-update add cron default

Add log rotate:

apk add logrotate

Edit ''/etc/logrotate.conf'' as desired, but the defaults should be sufficient for most people.

== Optional: Configure Web Server Virtual Domains ==

'''Note:''' These steps can be done ''in addition to'' the default lighttpd configuration above, which allows you to access the ACF, PostfixAdmin and Roundcube interfaces as subfolders of one web service.

'''Note:''' If you provide SSL access for multiple domain site you may need to follow http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:SSL#SSL-on-multiple-domains in order to provide multi-domain certificates. If you would like to redirect hosts to their secure equivalents use the following instructions http://redmine.lighttpd.net/projects/lighttpd/wiki/HowToRedirectHttpToHttps.

This server hosts three separate web applications, and these can be handled as three ''different'' virtual domains on the same web server. They will be distinguished by their DNS names, so you can choose domains for the three separate services (or at least the ones you want to publish):

* ACF - Alpine Configuration Framework for managing the server
* PostfixAdmin - for managing the postfix installation
* RoundCube - for accessing individual mailboxes

Choose three different domains (from here on known as ACF_DOMAIN, POSTFIXADMIN_DOMAIN, and ROUNDCUBE_DOMAIN) and configure DNS for all three to point to the IP address of your host. These should be DNS '''A''' records.

Then, configure lighttpd to handle the three separate domains by editing /etc/lighttpd/lighttpd.conf:

<pre>
$HTTP["host"] == "ACF_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/ACF_DOMAIN/"
simple-vhost.document-root = "www/"
}

$HTTP["host"] == "POSTFIXADMIN_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/POSTFIXADMIN_DOMAIN/"
simple-vhost.document-root = "www/"
}

$HTTP["host"] == "ROUNDCUBE_DOMAIN" {
simple-vhost.server-root = "/var/www/domains/"
simple-vhost.default-host = "/ROUNDCUBE_DOMAIN/"
simple-vhost.document-root = "www/"
}
</pre>

And, then link the appropriate www directories.
<pre>
mkdir -p /var/www/domains/ACF_DOMAIN
ln -s /usr/share/acf/www /var/www/domains/ACF_DOMAIN/www

mkdir -p /var/www/domains/POSTFIXADMIN_DOMAIN
ln -s /var/www/domains/host.example.com/www/postfixadmin /var/www/domains/POSTFIXADMIN_DOMAIN/www

mkdir -p /var/www/domains/ROUNDCUBE_DOMAIN
ln -s /usr/share/webapps/roundcube /var/www/domains/ROUNDCUBE_DOMAIN/www
</pre>

== Optional: Enable compression in Lighttpd ==

* Uncomment ''mod_compress'' and ''mod_setenv'' and modify website section as follows

mkdir -p /var/lib/lighttpd/cache
chown lighttpd:lighttpd /var/lib/lighttpd/cache

vi /etc/lighttpd/lighttpd.conf

...
"mod_setenv",
"mod_compress",
...
$HTTP["host"] == "ROUNDCUBE_DOMAIN" {
...
static-file.etags = "enable"
etag.use-mtime = "enable"
$HTTP["url"] =~ "^/(plugins|skins|program)" { setenv.add-response-header = ( "Cache-Control" => "public, max-age=2592000") }
compress.cache-dir = var.statedir + "/cache/compress"
compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml", "image/gif", "image/png")
}

[[Category:Mail]]
[[Category:PHP]]
[[Category:SQL]]
[[Category:ACF]]

Multiple Instances of Services

2016-07-26T23:38:59Z

Ttrask: Add ACF category

Alpine makes it very easy to install and run a service, but what if you need to have multiple instances of the same service running on the same machine. For instance, what if you want to run split-DNS, where you respond to DNS requests differently for internal and external networks. The simple response is to run two instances of tinyDNS listening on two different Ethernet interfaces. Now, how do you do it? How do you manage the two instances once you have them running?

The following example is specifically for TinyDNS, but can be applied to other services as well. TinyDNS will work because the init.d script has been written in such a way as to allow multiple instances. The procedure is written for alpine 1.9, but should work for other versions as well.

== Install The Service ==
First, we'll install TinyDNS and the ACF

{{Cmd|apk add acf-tinydns}}

This will install the TinyDNS service, as well as the ACF web interface used to manage the service. Having only one instance of TinyDNS, you can manage it from the console using /etc/init.d/tinydns, /etc/conf.d/tinydns, and /etc/tinydns/ or from ACF using the Networking > DNS pages.

== Create a Second Instance of the Service ==
Now, we create a symlink to the TinyDNS init.d script for each new instance you want to run. (For alpine 1.8, you should not use the plain tinydns init.d script so that ACF can properly determine which instance is running, but create two new instances instead) We're going to create a second instance that will handle the internal network.

{{Cmd|ln -s /etc/init.d/tinydns /etc/init.d/tinydns.internal}}

Create conf.d and domain files for each new script. You can copy the tinydns files to start.

{{Cmd|cp /etc/conf.d/tinydns /etc/conf.d/tinydns.internal
cp -r /etc/tinydns /etc/tinydns.internal}}

You now have a second instance of the TinyDNS service that you can manage from the console using /etc/init.d/tinydns.internal, /etc/conf.d/tinydns.internal, and /etc/tinydns.internal/. But, how do you manage it with ACF?

== Create a Second Instance of the ACF ==
Set up an ACF controller for the new script. Controller names can only contain letters, numbers, and '_'.

{{Cmd|mkdir /usr/share/acf/app/tinydns_internal}}

Set up the modified ACF code for each new script. Only three files must be modified, the others may be copied or symlink'd. The name of the controller must be changed to allow the ACF permissions of the two TinyDNS instances to be managed separately.

{{Cmd|cd /usr/share/acf/app/tinydns
for a in tinydns*; do cp $a /usr/share/acf/app/tinydns_internal/$(echo $a {{!}} sed "s/tinydns/tinydns_internal/"); done}}

{{Cmd|vim /usr/share/acf/app/tinydns_internal/tinydns_internal-model.lua}}
Change 'local processname = "tinydns.internal"'

{{Cmd|vim /usr/share/acf/app/tinydns_internal/tinydns_internal.roles}}
Replace each instance of 'tinydns' with 'tinydns_internal'

{{Cmd|vim /usr/share/acf/app/tinydns_internal/tinydns_internal.menu}}

Modifiy the main menu entry, ie. replace each instance of '30DNS' with '31DNS_Internal'

Once you log out and log back into ACF, you should see the new ACF pages and menu options available. User and role management can be handled separately for the new instance. (In alpine 1.8, users should not be given access to the plain TinyDNS ACF)

== Save Your Changes ==
The /usr/share directory is not automatically included in lbu commits, so the new ACF instance must be added manually.

{{Cmd|lbu add /usr/share/acf/app/tinydns_internal}}

Then, commit the changes.

{{Cmd|lbu commit}}

[[Category:Booting]]
[[Category:ACF]]

Html.lua

2016-07-26T23:34:17Z

Ttrask: Add ACF category

=html.lua =
This is used in the View section of the Model-Controller-View.

== cookie.set ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
* name
* value
* path
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
* String to set the cookie
'''CODING EXAMPLE:'''
-- Set variable/Call for this library

==html_escape ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*text-string
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
* String with &,>,< signs encoded
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
bobo = require "html"
format = bobo.html_escape("This is > a test < string &")
print(format)
This is > a test < string &

==nv_pair==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*name
*value
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
* name="value"
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
bobo = require "html"
format = bobo.nv_pair("foo", "bar")
print(format)
foo="bar"

==cfe_unpack ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Give a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*String with the whole cfe table
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--haserl code below. Used in views in ACF
<? require "html ?>

<?= html.cfe(form) ?>

==form.longtext ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <textarea>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="longtext", rows="30", cols="20" })
--your cfe will look something like this
{ value=status, type="longtext", options="", errtxt="" , rows="30, cols="20"}
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.passwd ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=password>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="passwd" })
--your cfe will look something like this
{ value=status, type="passwd", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.hidden==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=hidden>
'''CODING EXAMPLE:''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="hidden" })
--your cfe will look something like this
{ value=status, type="hidden", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.submit==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=submit>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="submit" })
--your cfe will look something like this
{ value=status, type="submit", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.action ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=submit>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="submit" })
--your cfe will look something like this
{ value=status, type="submit", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.file ==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=file>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="file" })
--your cfe will look something like this
{ value=status, type="file", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.image==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=image>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="image" })
--your cfe will look something like this
{ value=status, type="image", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.select==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <select>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="select" option= {"yes", "no", "maybe", "so" } })
--your cfe will look something like this
{ value=status, type="select", options="", errtxt="" option= {"yes", "no", "maybe", "so"} }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==form.checkbox==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*Needs a cfe table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=checkbox>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
return (cfe{value=status, name="inputarea", type="checkbox" })
--your cfe will look something like this
{ value=status, type="checkbox", options="", errtxt="" }
--haserl code below. Used in views in ACF

<? require "html" ?>
<?= html.form[form.value.inputarea.type](form.value.inputarea) ?>
--this way will only have to touch model/controller if change in code. Very rarely the view.

==link==
'''INPUT:'''<BR>
This library required the following inputs/parameters.
*A table
'''OUTPUT:'''<BR>
This library deliverers the following output/parameters.
*Html code for a <input type=password>
'''CODING EXAMPLE:'''
-- Set variable/Call for this library
--your model may return something like this
url="http://localhost/cgi-bin/acf/"
<? require "html" ?>
<?= html.link{value = url .. varible.url, label="Download"}?>

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

Algo 8180 Provisioning With ACF

2016-07-26T23:27:00Z

Ttrask: Add ACF category

{{Draft}}
= Overview =
This page describes how to provision [http://algosolutions.com/products/Audible-and-Visual-Alerting/8180-sip-audio-alerter.html Algo 8180] devices using [[SIP Provisioning On Alpine Linux]] based upon the ACF web interface. It is supported starting with Alpine Linux 3.2.

= Setup Procedure=
== 1. Install provisioning server ==
First, install the provisioning server according to the instructions at [[SIP Provisioning On Alpine Linux | this page]].
== 2. Install firmware package ==
The latest supported firmware is included in a package:
apk add acf-provisioning-algo
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM. You can use the following command: apk fetch --quiet --stdout acf-provisioning-algo | tar -C / -zvx}}
== 3. Configure init.cfg ==
The Algo will override ALL parameters when it is provisioned. If parameters are not provided by the provisioning server, they will be reset to default. Since not all parameters are included in the provisioning database, they must be configured statically in ''/var/www/provisioning/htdocs/Algo/init.cfg''. You can use ''/var/www/provisioning/htdocs/Algo/init.cfg.sample'' as a starting point. You will probably need to modify the network configuration and provisioning server IP.
cp /var/www/provisioning/htdocs/Algo/init.cfg.sample /var/www/provisioning/htdocs/Algo/init.cfg
== 4. Configure the Algo 8180 to connect to the provisioning server ==
Unfortunately, the DHCP option 66 does not seem to work in our testing. So, you must manually configure the Algo to connect to the provisioning server. Once you get the Algo device connected to the network, follow these steps:
*MENU Advanced Settings > Provisioning
**Provisioning Mode: Enabled
**Server Method: Static
**Static Server: Enter the IP address or FQDN of the provisioning server
**Download Method: HTTP
**Config Download Path: Algo
**Firmware Download Path: Algo

[[Category:ACF]]

Freeswitch Voicemail On Alpine Linux

2016-07-13T17:45:23Z

Ttrask: Add instructions to record in mp3 format

= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items are not needed for Alpine Linux 3.2 or later. They are needed on earlier versions due to bad default paths in the Freeswitch package.}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to one of the Freeswitch default local extensions (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf
Change the ACF voicemail domain to match the domain from the sample config. You should use the IP address of your voicemail server, as this is what the sample config uses.
sed -i /^domain=/d /etc/freeswitchvmail.conf
echo "domain=IPADDRESS" >> /etc/freeswitchvmail.conf

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the Freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The Freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused. Once again, to dial into Freeswitch you can use one of the Freeswitch default local extensions as explained above.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

= Other Features =
== Switching From wav to mp3 Recording (Recommended) ==
{{Note|The mp3 format is supported in acf-freeswitch-vmail-0.6.2 and later, available on Alpine Linux 3.2 or later.}}
By default, Freeswitch will store voicemail recordings in wav format. Freeswitch also has the option of storing the recordings in mp3 format if mod_shout is installed. As mp3 format requires less storage/bandwidth and enjoys better support by web browsers, I would recommend making this change:
=== 1. Add the mod_shout module ===
Modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_shout module
<load module="mod_shout"/>
=== 2. Change Record Format to mp3 ===
sed -i s/'name="file-extension" value="wav"'/'name="file-extension" value="mp3"'/ /etc/freeswitch/autoload_configs/voicemail.conf.xml
=== 3. Restart Freeswitch ===
/etc/init.d/freeswitch restart
== Using PostgreSQL ==
Freeswitch-1.2.5 and acf-freeswitch-vmail-0.5.0 fully support Postgresql as the voicemail database. These versions are available in Alpine Linux 3.2 and later. To configure it:
=== 1. Install Postgresql ===
apk add postgresql acf-postgresql
=== 2. Setup and Start Postgresql ===
rc-update add postgresql
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
=== 3. Create the Database ===
psql -U postgres -c "CREATE DATABASE voicemail"
=== 4. Stop Freeswitch ===
/etc/init.d/freeswitch stop
{{Note|Freeswitch does not always stop properly. You might need to run 'ps ax' to find the process and 'kill' it. Running '/etc/init.d/freeswitch zap' might also be necessary.}}
=== 5. Configure Freeswitch and acf-freeswitch-vmail ===
Edit /etc/freeswitch/autoload_configs/voicemail.conf.xml to set the odbc-dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
<param name="odbc-dsn" value="pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''" />
Edit /etc/freeswitchvmail.conf and set the dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
dsn=pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''
=== 6. Restart Freeswitch ===
/etc/init.d/freeswitch start

[[Category:ACF]]

ACF mvc.lua example

2016-04-30T01:50:36Z

Ttrask: Remove obsolete example and changes to view_resolver

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an Alpine Linux box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes the form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.set_hostname, self.clientdata, "Update", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and set the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Hostname" })

-- Warning - io.popen has security risks, never pass user data to io.popen
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.value.hostname = cfe({ value=n, label="Hostname" })

return retval
end

-- Set the hostname from the value contained in the cfe created by get_hostname
mymodule.set_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be 16 characters or less"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is valid, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
-- Warning - io.popen has security risks, never pass user data to io.popen
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to set hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.set_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the action string passed to acf-cli is of the form "/prefix/controller/action". The prefix is the path within /etc/acf/app where the controller may be found, so "/test/" for our case. The controller is determined from the controller file name, so "hostname" for our case. And, the action corresponds to the function within the controller to call, so "edithostname" for our case. Also note that, in the two examples above, the first case reads the existing hostname and the second case updates it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is determined by the view.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions or model functions. Using the controller actions requires use of the clientdata structure to pass parameters. For calling the model functions, the application will call the get function to retrieve the form cfe, fill in the desired input values into the cfe, and then call the set function to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
==== test_dispatch ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=arg[1], viewtype=arg[2], submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()

Test the application. As can be seen in the code above, the first argument is the new hostname and the second is a viewtype.

alpine:~# chmod 755 test_dispatch
alpine:~# ./test_dispatch test
test:~# ./test_dispatch alpine
alpine:~#

Note that the application functions, but there is no output. This is because there is no viewtype supplied. There is built-in support for these standard viewtypes (not all apply): html, json, stream, serialized

alpine:~# ./test_dispatch test serialized
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Update"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"
test:~# ./test_dispatch alpine json
{"type":"form","label":"Edit Hostname","value":{"hostname":{"value":"alpine","type":"text","label":"Hostname"}},"option":"Update","descr":"Hostname Updated"}
alpine:~#

You can also use a custom viewtype and/or view to customize the output. This relies on haserl to parse the view file, and haserl lua functions are only available when launched from haserl scripts (it would be nice if haserl were available as a standalone lua library). Haserl scripts expect to be launched by a web browser to handle CGI data, so passing input is trickier. I'm sure there is a better way to do this, but this is just an example:

==== test_haserl ====
#!/usr/bin/haserl-lua5.2 --shell=lua
<%
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=FORM.hostname, viewtype=FORM.viewtype, submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()
%>

==== /etc/acf/app/test/hostname-edithostname-text.lsp ====
<%
local data, viewlibrary, page_info, session = ...

if data.errtxt then
print(data:print_errtxt())
else
print(data.descr)
end
%>

Test the application

test:~# chmod 755 test_haserl
test:~# QUERY_STRING='hostname=alpine&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Hostname Updated
alpine:~# QUERY_STRING='hostname=asdfasdfasdfasdfasdf&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

=== Use the New method ===
==== test_new ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- load the hostname controller
HOSTNAME=MVC:new("/test/hostname")

local hostname

-- METHOD 1 - controller action
HOSTNAME.clientdata = {hostname=arg[1], submit="Update"}
hostname = HOSTNAME:edithostname()

-- METHOD 2 - model functions
hostname = HOSTNAME.model:get_hostname()
hostname.value.hostname.value = arg[1]
hostname = HOSTNAME.model:set_hostname(hostname)

if hostname.errtxt then
print(hostname:print_errtxt())
else
print(hostname.descr or "Hostname Updated")
end

HOSTNAME:destroy()
MVC:destroy()

Once you have a hostname controller object, you can access its actions, passing data through clientdata, or you can directly access the get/set functions of the model. Test the app:

test:~# chmod 755 test_new
test:~# ./test_new alpine
Hostname Updated
alpine:~# ./test_new asdfasdfasdfasdfasdf
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

{{Obsolete}}

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ACF mvc.lua example

2016-04-30T01:42:16Z

Ttrask: Added example of MVC app using new method

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an Alpine Linux box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes the form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.set_hostname, self.clientdata, "Update", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and set the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Hostname" })

-- Warning - io.popen has security risks, never pass user data to io.popen
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.value.hostname = cfe({ value=n, label="Hostname" })

return retval
end

-- Set the hostname from the value contained in the cfe created by get_hostname
mymodule.set_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be 16 characters or less"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is valid, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
-- Warning - io.popen has security risks, never pass user data to io.popen
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to set hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.set_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the action string passed to acf-cli is of the form "/prefix/controller/action". The prefix is the path within /etc/acf/app where the controller may be found, so "/test/" for our case. The controller is determined from the controller file name, so "hostname" for our case. And, the action corresponds to the function within the controller to call, so "edithostname" for our case. Also note that, in the two examples above, the first case reads the existing hostname and the second case updates it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is determined by the view.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions or model functions. Using the controller actions requires use of the clientdata structure to pass parameters. For calling the model functions, the application will call the get function to retrieve the form cfe, fill in the desired input values into the cfe, and then call the set function to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
==== test_dispatch ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=arg[1], viewtype=arg[2], submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()

Test the application. As can be seen in the code above, the first argument is the new hostname and the second is a viewtype.

alpine:~# chmod 755 test_dispatch
alpine:~# ./test_dispatch test
test:~# ./test_dispatch alpine
alpine:~#

Note that the application functions, but there is no output. This is because there is no viewtype supplied. There is built-in support for these standard viewtypes (not all apply): html, json, stream, serialized

alpine:~# ./test_dispatch test serialized
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Update"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"
test:~# ./test_dispatch alpine json
{"type":"form","label":"Edit Hostname","value":{"hostname":{"value":"alpine","type":"text","label":"Hostname"}},"option":"Update","descr":"Hostname Updated"}
alpine:~#

You can also use a custom viewtype and/or view to customize the output. This relies on haserl to parse the view file, and haserl lua functions are only available when launched from haserl scripts (it would be nice if haserl were available as a standalone lua library). Haserl scripts expect to be launched by a web browser to handle CGI data, so passing input is trickier. I'm sure there is a better way to do this, but this is just an example:

==== test_haserl ====
#!/usr/bin/haserl-lua5.2 --shell=lua
<%
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=FORM.hostname, viewtype=FORM.viewtype, submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()
%>

==== /etc/acf/app/test/hostname-edithostname-text.lsp ====
<%
local data, viewlibrary, page_info, session = ...

if data.errtxt then
print(data:print_errtxt())
else
print(data.descr)
end
%>

Test the application

test:~# chmod 755 test_haserl
test:~# QUERY_STRING='hostname=alpine&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Hostname Updated
alpine:~# QUERY_STRING='hostname=asdfasdfasdfasdfasdf&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

=== Use the New method ===
==== test_new ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- load the hostname controller
HOSTNAME=MVC:new("/test/hostname")

local hostname

-- METHOD 1 - controller action
HOSTNAME.clientdata = {hostname=arg[1], submit="Update"}
hostname = HOSTNAME:edithostname()

-- METHOD 2 - model functions
hostname = HOSTNAME.model:get_hostname()
hostname.value.hostname.value = arg[1]
hostname = HOSTNAME.model:set_hostname(hostname)

if hostname.errtxt then
print(hostname:print_errtxt())
else
print(hostname.descr or "Hostname Updated")
end

HOSTNAME:destroy()
MVC:destroy()

Once you have a hostname controller object, you can access its actions, passing data through clientdata, or you can directly access the get/set functions of the model. Test the app:

test:~# chmod 755 test_new
test:~# ./test_new alpine
Hostname Updated
alpine:~# ./test_new asdfasdfasdfasdfasdf
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

{{Obsolete}}
4. Create a dispatch wrapper program, named '''helloworld.lua''' in the current directory:

-- Simple CLI based mvc application

-- this is to get around having to store
-- the config file in /etc/helloworld/helloworld.conf
ENV={}
ENV.HOME="."

-- load the module
require("mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("helloworld")

-- create an application container
APP=MVC:new("app")

-- dispatch the request
APP.clientdata.hostname=arg[2]
APP:dispatch( "", "hostname", (arg[1] or ""))

-- destroy the mvc objects
APP:destroy()
MVC:destroy()

This application loads the "mvc.lua" framework, creates an mvc "object" named "MVC", then reads the helloworld.conf file to find out where the app dir is (helloworld/app/). It then loads the '''app-controller.lua''' into a new "application level" object named '''APP'''. Finally, it sets the clientdata and dispatches the hostname-controller/model pair.

5. Test the application:
# hostname
Alpine
# lua helloworld.lua no-such-function foo
The following unhandled application error occured:

controller: "hostname" does not have a "no-such-function" action.
# hostname
Alpine

# hostname
Alpine
# lua helloworld.lua update Alline
Your controller and application did not specify a view resolver.
The MVC framework has no view available. sorry.
# hostname
Alline

Note in the second case the hostname ''was'' changed, although the application does not know how to report success.

== Create a view resolver and view formatter ==

The view resolver is a function that returns a function that processes the view. The returned function receives input from the controller and generates the output to be displayed.

We will build a very simple view resolver and view processor for our application. Add this to the end of '''helloworld/app/hostname-controller.lua'''

local private = {}

private.view = function (f)
if (f.msg) then
print( (f.value or "") .. " is not a valid hostname ")
else
print ("Hostname is currently " .. f.value )
end
end

view_resolver = function (self)
return private.view
end

Now we can test:

# lua helloworld.lua update "1 2 3"
1 2 3 is not a valid hostname
# lua helloworld.lua update
is not a valid hostname
# lua helloworld.lua update Alpine
Hostname is currently Alpine

But we have two problems:

1. We now have to make a view resolver and view function for every controller. If we add a ''date'' setting controller, we'll have to make a view resolver and view function for it, and so on.

2. Perhaps more importantly, view_resolver is now an "action" in our appliction. Recall that invalid actions are captured, but try this:

# lua helloworld.lua no_such_action Alpine
The following unhandled application error occured:

controller: "hostname" does not have a "no_such_action" action.

# lua helloworld.lua view_resolver Alpine
The following unhandled application error occured:

./helloworld/app/hostname-controller.lua:27: attempt to index local 'f' (a function value)
stack traceback:
./helloworld/app/hostname-controller.lua:27: in function 'viewfunc'
./mvc.lua:139: in function <./mvc.lua:90>
[C]: in function 'xpcall'
./mvc.lua:90: in function 'dispatch'
helloworld.lua:23: in main chunk
[C]: ?

Because view_resolver is an action in the worker table, the '''mvc.lua''' runs it; but it returns a function, not a table, and causes an unhandled exception in the view.

== Move the view resolver to the application level ==

The solution to both problems is to move the view resolver and the view function out of the controller's worker table, into the next higher level, in this case, the application's worker table:

1. Delete the private.view and view_resolver functions from '''helloworld/app/hostname-controller.lua'''

2. Add the following to '''helloworld/app/app-controller.lua'''

local private = {}

private.view = function ( controller, action, viewtable )
io.write(string.format("Controller: %s Action: %s\n",
controller or "", action or ""))
io.write ("Returned a table with the following values:\n")

for k,v in pairs(viewtable) do
io.write(string.format("%s\t%s\n", k, v))
end
end

view_resolver = function (self)
return function (viewtable)
return private.view (self.conf.controller, self.conf.action, viewtable)
end
end

This creates a more "generic" view, but one that will work for any controller - not just '''hostname'''.

Now things work as they should:

# lua helloworld.lua update "one two"
Controller: hostname Action: update
Returned a table with the following values:
value one two
type string
msg Hostname can contain alphanumerics only

# lua helloworld.lua view_resolver "Alpine"
The following unhandled application error occured:

controller: "hostname" does not have a "view_resolver" action.

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ACF mvc.lua example

2016-04-30T01:11:17Z

Ttrask: Add example of MVC application using dispatch method

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an Alpine Linux box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes the form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.set_hostname, self.clientdata, "Update", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and set the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Hostname" })

-- Warning - io.popen has security risks, never pass user data to io.popen
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.value.hostname = cfe({ value=n, label="Hostname" })

return retval
end

-- Set the hostname from the value contained in the cfe created by get_hostname
mymodule.set_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be 16 characters or less"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is valid, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
-- Warning - io.popen has security risks, never pass user data to io.popen
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to set hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.set_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the action string passed to acf-cli is of the form "/prefix/controller/action". The prefix is the path within /etc/acf/app where the controller may be found, so "/test/" for our case. The controller is determined from the controller file name, so "hostname" for our case. And, the action corresponds to the function within the controller to call, so "edithostname" for our case. Also note that, in the two examples above, the first case reads the existing hostname and the second case updates it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is determined by the view.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions. For handling forms and user input, the application will call the action once to retrieve the form cfe, then fill in the desired input values into the cfe and call the action again to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
==== test_dispatch ====
#!/usr/bin/lua
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=arg[1], viewtype=arg[2], submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()

Test the application. As can be seen in the code above, the first argument is the new hostname and the second is a viewtype.

alpine:~# chmod 755 test_dispatch
alpine:~# ./test_dispatch test
test:~# ./test_dispatch alpine
alpine:~#

Note that the application functions, but there is no output. This is because there is no viewtype supplied. There is built-in support for these standard viewtypes (not all apply): html, json, stream, serialized

alpine:~# ./test_dispatch test serialized
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Update"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"
test:~# ./test_dispatch alpine json
{"type":"form","label":"Edit Hostname","value":{"hostname":{"value":"alpine","type":"text","label":"Hostname"}},"option":"Update","descr":"Hostname Updated"}
alpine:~#

You can also use a custom viewtype and/or view to customize the output. This relies on haserl to parse the view file, and haserl lua functions are only available when launched from haserl scripts (it would be nice if haserl were available as a standalone lua library). Haserl scripts expect to be launched by a web browser to handle CGI data, so passing input is trickier. I'm sure there is a better way to do this, but this is just an example:

==== test_haserl ====
#!/usr/bin/haserl-lua5.2 --shell=lua
<%
-- Simple CLI based mvc application

-- load the mvc module
mvc = require("acf.mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("acf")

-- dispatch the request
local clientdata = {hostname=FORM.hostname, viewtype=FORM.viewtype, submit="Update"}
MVC:dispatch("/test/", "hostname", "edithostname", clientdata)

-- destroy the mvc object
MVC:destroy()
%>

==== /etc/acf/app/test/hostname-edithostname-text.lsp ====
<%
local data, viewlibrary, page_info, session = ...

if data.errtxt then
print(data:print_errtxt())
else
print(data.descr)
end
%>

Test the application

test:~# chmod 755 test_haserl
test:~# QUERY_STRING='hostname=alpine&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Hostname Updated
alpine:~# QUERY_STRING='hostname=asdfasdfasdfasdfasdf&viewtype=text' REQUEST_METHOD=GET ./test_haserl
Failed to set hostname
hostname: Hostname must be 16 characters or less
alpine:~#

=== Use the New method ===
Todo

{{Obsolete}}
4. Create a dispatch wrapper program, named '''helloworld.lua''' in the current directory:

-- Simple CLI based mvc application

-- this is to get around having to store
-- the config file in /etc/helloworld/helloworld.conf
ENV={}
ENV.HOME="."

-- load the module
require("mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("helloworld")

-- create an application container
APP=MVC:new("app")

-- dispatch the request
APP.clientdata.hostname=arg[2]
APP:dispatch( "", "hostname", (arg[1] or ""))

-- destroy the mvc objects
APP:destroy()
MVC:destroy()

This application loads the "mvc.lua" framework, creates an mvc "object" named "MVC", then reads the helloworld.conf file to find out where the app dir is (helloworld/app/). It then loads the '''app-controller.lua''' into a new "application level" object named '''APP'''. Finally, it sets the clientdata and dispatches the hostname-controller/model pair.

5. Test the application:
# hostname
Alpine
# lua helloworld.lua no-such-function foo
The following unhandled application error occured:

controller: "hostname" does not have a "no-such-function" action.
# hostname
Alpine

# hostname
Alpine
# lua helloworld.lua update Alline
Your controller and application did not specify a view resolver.
The MVC framework has no view available. sorry.
# hostname
Alline

Note in the second case the hostname ''was'' changed, although the application does not know how to report success.

== Create a view resolver and view formatter ==

The view resolver is a function that returns a function that processes the view. The returned function receives input from the controller and generates the output to be displayed.

We will build a very simple view resolver and view processor for our application. Add this to the end of '''helloworld/app/hostname-controller.lua'''

local private = {}

private.view = function (f)
if (f.msg) then
print( (f.value or "") .. " is not a valid hostname ")
else
print ("Hostname is currently " .. f.value )
end
end

view_resolver = function (self)
return private.view
end

Now we can test:

# lua helloworld.lua update "1 2 3"
1 2 3 is not a valid hostname
# lua helloworld.lua update
is not a valid hostname
# lua helloworld.lua update Alpine
Hostname is currently Alpine

But we have two problems:

1. We now have to make a view resolver and view function for every controller. If we add a ''date'' setting controller, we'll have to make a view resolver and view function for it, and so on.

2. Perhaps more importantly, view_resolver is now an "action" in our appliction. Recall that invalid actions are captured, but try this:

# lua helloworld.lua no_such_action Alpine
The following unhandled application error occured:

controller: "hostname" does not have a "no_such_action" action.

# lua helloworld.lua view_resolver Alpine
The following unhandled application error occured:

./helloworld/app/hostname-controller.lua:27: attempt to index local 'f' (a function value)
stack traceback:
./helloworld/app/hostname-controller.lua:27: in function 'viewfunc'
./mvc.lua:139: in function <./mvc.lua:90>
[C]: in function 'xpcall'
./mvc.lua:90: in function 'dispatch'
helloworld.lua:23: in main chunk
[C]: ?

Because view_resolver is an action in the worker table, the '''mvc.lua''' runs it; but it returns a function, not a table, and causes an unhandled exception in the view.

== Move the view resolver to the application level ==

The solution to both problems is to move the view resolver and the view function out of the controller's worker table, into the next higher level, in this case, the application's worker table:

1. Delete the private.view and view_resolver functions from '''helloworld/app/hostname-controller.lua'''

2. Add the following to '''helloworld/app/app-controller.lua'''

local private = {}

private.view = function ( controller, action, viewtable )
io.write(string.format("Controller: %s Action: %s\n",
controller or "", action or ""))
io.write ("Returned a table with the following values:\n")

for k,v in pairs(viewtable) do
io.write(string.format("%s\t%s\n", k, v))
end
end

view_resolver = function (self)
return function (viewtable)
return private.view (self.conf.controller, self.conf.action, viewtable)
end
end

This creates a more "generic" view, but one that will work for any controller - not just '''hostname'''.

Now things work as they should:

# lua helloworld.lua update "one two"
Controller: hostname Action: update
Returned a table with the following values:
value one two
type string
msg Hostname can contain alphanumerics only

# lua helloworld.lua view_resolver "Alpine"
The following unhandled application error occured:

controller: "hostname" does not have a "view_resolver" action.

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

GNOME

2016-03-25T17:42:47Z

Ttrask: Add a link to community repo

{{Draft|It doesn't produce the result expected YET}}
= Initial setup =
Start by booting up Alpine (see [[Installation|these]] instructions on how to do that)<BR>
When you Alpine is up and running, do the initial setup.
{{Cmd|setup-alpine}}
{{Cmd|setup-xorg-base}}

= Install packages =
Install basic desktop system and gnome packages. For Alpine Linux 3.3 and later, these packages are in the [[Enable_Community_Repository|community]] repo.<BR>
This might take a few minutes depending on your network speed.
{{Cmd|apk add alpine-desktop gnome-base lxdm}}
<BR>
Lxdm is a display manager. You can use a different one such as slim by replacing {{Cmd|lxdm}} with {{Cmd|slim}}

== Optional packages ==
=== Video and Input packages ===
You <u>might</u> also want to install a package suitable for your video chipset and input devices.<BR>
For example, if you have an Sis video chipset install 'xf86-video-sis', for Intel video chipset install 'xf86-video-intel'.<BR>
{{Cmd|apk add xf86-video-sis}}
and / or
{{Cmd|apk add xf86-input-synaptics}}

If you are running a virtual machine (i.e in VirtualBox or VMware) you probably also want these video drivers:
{{Cmd|apk add xf86-video-vmware}}

Run 'apk search xf86-video*' to see available xf86-video packages.<BR>
Run 'apk search xf86-input*' to see available xf86-input packages.<BR>

=== acpid ===
If you installed your Alpine Linux as a VirtualBox or VMWare guest you might find it handy be able send ACPI shutdown.<BR>
{{Cmd|rc-update add acpid}}

= Configure xorg-server (optional) =
You can configure xorg-server and make your modifications
{{Cmd|Xorg -configure}}
This will result in `/root/xorg.conf.new`. You can modify this file to fit your needs.<BR>
(When finished modifying and testing the above configuration file, move it to `/etc/X11/xorg.conf` for normal usage.)

== udev ==
Adding udev might help you with some finicky hardware like touchpads.
{{Cmd|apk add udev
/etc/init.d/udev start && /etc/init.d/udev-postmount start
rc-update add udev sysinit
rc-update add udev-postmount default
}}
Adding evdev might also be necessary, for example if the keyboard doesn't work in X...
{{Cmd|apk add xf86-input-evdev}}

= Create user accounts =
Create a normal user account.
{{Cmd|adduser ncopa}}

Optionally, give that user sudo permissions in /etc/sudoers.

= Start your desktop =
Start lxdm and log in with your new user.
{{Cmd|rc-service lxdm start}}

Once you have verified that it actually works you can make lxdm start up at boot:
{{Cmd|rc-update add lxdm}}

Or if using slim:

{{Cmd|rc-service slim start}}

and once confirmed as working enable it at boot:
{{Cmd|rc-update add slim}}

= Troubleshooting =
If you are unable to login, check /var/log/lxdm.log, there may be output there from X to indicate failed modules, etc.
<BR>
If you are unable to login, or you see an error "Failed to execute login command", you should check ~/.xinitrc with your preferred text editor (vi, nano, etc) and ensure that it is set to boot into gnome. To do this, the 'exec' line (usually the last line in the file) should read "exec gnome-session".
If ~/.xinitrc does not exist, create it and add the exec line. this command will do it:

{{Cmd|touch ~/.xinitrc && echo "exec gnome-session" >> ~/.xinitrc}}

[[Category:Desktop]]

Enable Community Repository

2016-03-25T17:41:34Z

Ttrask: New page

Starting with Alpine Linux version 3.3, there is a new repository called '''community'''. Many packages have been moved from the main repository to community to indicate that they are not guaranteed to be supported beyond six months. If you are using any of these packages, be sure to add the community repository.

Edit the {{Path|/etc/apk/repositories}} file using an editor ({{Pkg|nano}} for instance) and add (or uncomment) a line like:

'''http://dl-6.alpinelinux.org/alpine/edge/community'''

After adding the community repository, obtain the latest index of available packages:
{{Cmd|apk update}}

{{Tip|Adding the <code>-U</code>/<code>--update-cache</code> to another apk command, as in <code>apk add -U ...</code> or <code>apk upgrade -U</code>, has the same effect as running <code>apk update</code> before the other apk command.}}

Aports tree

2016-02-25T04:44:58Z

Ttrask: Add community, state that testing is only for edge

The [http://git.alpinelinux.org/cgit/aports/ aports] tree contains for every package/program a directory with the corresponding [[APKBUILD_Reference|APKBUILD]] file. ''[http://git.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' is a file containing "recipes" on how something should be built/compiled. These files are used when building alpine from source.

When Alpine Linux is compiled, you will no longer see (or have use of) the APKBUILD. It is not included in the 'iso' or 'tar.gz'. The [[Abuild|abuild]] script reads the APKBUILD and executes the steps needed to create a package.

== Directories ==
There are some directories placed in the [http://git.alpinelinux.org/cgit/aports/ aports] tree. A short description of every directory can be found in this section.

=== main ===
''main'' contains the basic set of packages for Alpine Linux.

=== community ===
''community'' contains the additional packages that, for various reasons, are not guaranteed to be supported beyond six months.

=== testing ===
All new packages goes to ''testing'' first. Package will be moved to ''main'' if there positive feedback or other good reasons. Packages in ''testing'' are not included in stable builds, but are only built for edge.

=== non-free ===
The packages in ''non-free'' are violating the standards of the [http://www.fsf.org/ Free Software Foundation] (FSF) about copying, redistributing, and modifying computer programs in one or another way.

=== unmaintained ===
When a package is no longer maintained and no longer builds, it is moved to 'unmaintained'. It is mostly to not break the build servers while still have to original APKBUILD available in case someone feels for fixing it.

== Fetch latest APKBUILD files ==
While inside your [[Setting up the build environment 1.9|build environment]] you need to install some needed packages and you need to fetch the APKBUILD's from the server (fetch the aports tree).<BR>
'''''Note:''' You only need to do these 2 steps once! Next time you can skip this part.''
{{Cmd|apk add alpine-sdk}}
{{Cmd|cd ~}}
{{Cmd|git clone git://dev.alpinelinux.org/aports}}
When the above is done you might be interested in fetching the latest updates.
{{Cmd|cd ~/aports}}
{{Cmd|git pull}}

[[Category:Development]]

Include:Using Internet Repositories for apk-tools

2016-02-03T13:54:05Z

Ttrask: Add community repo

Edit the {{Path|/etc/apk/repositories}} file using an editor ({{Pkg|nano}} for instance) and if necessary, add references to the Alpine package repositories. In the example below, the reference to the Alpine CD is maintained, so that if the requested package is available on the local media, it will be obtained from there instead of being downloaded from the remote repository:

{{Cat|/etc/apk/repositories|/media/cdrom/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main}}

Another example:
upgrading from version 2.6 to 2.7 simply change:
<code><nowiki>http://dl-3.alpinelinux.org/alpine/v2.6/main</nowiki></code>
to
<code><nowiki> http://dl-3.alpinelinux.org/alpine/v2.7/main</nowiki></code>
Thus, the file will now look like this:
{{Cat|/etc/apk/repositories|/media/cdrom/apks
http://dl-3.alpinelinux.org/alpine/v2.7/main}}

{{Note|Starting with version 3.3, there is a new repository called '''community'''. Many packages have been moved from the main repository to community to indicate that they are not guaranteed to be supported beyond six months. If you are using any of these packages, be sure to add the community repository. For example: <code><nowiki>http://dl-3.alpinelinux.org/alpine/v3.3/community</nowiki></code>}}

Only one repository is shown above; however, you may also replace <code><nowiki>http://dl-3.alpinelinux.org/alpine/</nowiki></code> with any of the mirrors below:
{{Mirrors}}

After updating the repositories file, obtain the latest index of available packages:
{{Cmd|apk update}}

{{Tip|Adding the <code>-U</code>/<code>--update-cache</code> to another apk command, as in <code>apk add -U ...</code> or <code>apk upgrade -U</code>, has the same effect as running <code>apk update</code> before the other apk command.}}

ACF core principles

2016-01-13T19:54:45Z

Ttrask: Remove CRUD section, remove function type, change table type to structure

While the mvc.lua code provides a generic framework for any lua "mvc"-based application, "acf" is the component that makes the mvc.lua framework into a web configuration Application. Some ideas and rationales for application-wide settings are discussed here.

= Use of ''cfe'' =

A ''cfe'' ('''C'''onfiguration '''F'''ramework '''E'''ntity) is a way to pass data between a model, controller and view in a common way. There are many ways to do this (e.g. closures, AKClass); use of cfe is an arbitrary decision just to keep development moving forward.

A cfe is a table with some fields guaranteed to exist. It is also a way to abstract user-modifiable data from view-centric HTML input types. ACF isn't necessarily web-only. With a different controller and views, it could be cli (or gui?!). The acf-cli application is an example of this.

== Fields in all cfes ==

cfe's are constructed from a function in <tt>mvc.lua</tt> that returns an anonymous table with the following fields

{| border=1
! Field !! Default !! Description
|-
|value || "" || The value of the cfe (e.g. the IP address, hostname, password, etc.)
|-
|type || "text" || The type of entity (see below)
|-
|label || "" || User-readable label for the value
|}

The reason for having these fields pre-defined is to allow models, controllers and views to use the indexes without having to first check if they exist. For example the entity will always have a value and type.

cfe's can have other fields. Some common fields that may, or may not, be present:

{| border=1
! Field !! Description
|-
|errtxt || Text explaining why validation failed
|-
|option || A list of options for this value
|-
|descr || User-readable description for the value
|-
|seq || Numeric sequence suggesting display order for cfe's in a group or form
|-
|default || Default value (can be displayed to user)
|-
|readonly || If present, indicates that the information is to be displayed, but not editable, typically used in forms
|}

To set fields or overwrite field defaults, specify a table in the argument list to the cfe constructor:

:mycfe = cfe({label="User", value="asdf", errtxt="Invalid User"})
is equivalent to
:mycfe = {label="User", value="asdf", type="text", errtxt="Invalid User"}

== cfe types ==

The ''type'' field of a cfe can be one of the following:

{| border=1
! type !! Description !! Modifiers
|-
| text || a text field, typically one line of text ||
|-
| longtext || a multi-line text field, like a textarea ||
|-
| select || a select list || ''value'' is the currently selected item <br>''option'' is an array of select options
|-
| multi || a multi-select list || ''value'' is an array of selected items <br>''option'' is an array of select options
|-
| list || a list || ''value'' is an array of strings
|-
| boolean || true or false ||
|-
| raw || raw binary data ||
|-
| form || a set of cfe's that make up a form || ''value'' is a table of cfe's that make up a form (the table should be name-indexed)<br>''option'' is the command name to save changes (button name for HTML)<br>''descr'' or ''errtxt'' may contain the result of a save attempt
|-
| group || a set of cfe's that make up an anonymous group || ''value'' is a table of grouped cfe's (can be used to pass several items to a view) (the table should be name-indexed)
|-
| structure || a Lua table with no further type info ||
|-
| password || a password which should not be readable by a user ||
|-
| hidden || a hidden field typically containing information used by ACF and not visible to a user ||
|}

= The Model defines the object set =

The model is responsible for writing and reading from the running system. The model typically does not need to know which part of a specific acf module it is running under. It is not mandatory that the model be lua "oop" as the rest of the system is. (the model may not have any need to know "self")

Since the model can choose how much or how little of the system to expose, the basic data set should be defined in the model.

[[Category:ACF]]

Algo 8180 Provisioning With ACF

2015-06-09T19:13:25Z

Ttrask: Manual firmware update is not necessary anymore

Algo 8180 Provisioning With ACF

2015-06-09T16:04:46Z

Ttrask: Add manual firmware upgrade

{{Draft}}
= Overview =
This page describes how to provision [http://algosolutions.com/products/Audible-and-Visual-Alerting/8180-sip-audio-alerter.html Algo 8180] devices using [[SIP Provisioning On Alpine Linux]] based upon the ACF web interface. It is supported starting with Alpine Linux 3.2.

= Setup Procedure=
== 1. Install provisioning server ==
First, install the provisioning server according to the instructions at [[SIP Provisioning On Alpine Linux | this page]].
== 2. Install firmware package ==
The latest supported firmware is included in a package:
apk add acf-provisioning-algo
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM. You can use the following command: apk fetch --quiet --stdout acf-provisioning-algo | tar -C / -zvx}}
== 3. Configure init.cfg ==
The Algo will override ALL parameters when it is provisioned. If parameters are not provided by the provisioning server, they will be reset to default. Since not all parameters are included in the provisioning database, they must be configured statically in ''/var/www/provisioning/htdocs/Algo/init.cfg''. You can use ''/var/www/provisioning/htdocs/Algo/init.cfg.sample'' as a starting point. You will probably need to modify the network configuration and provisioning server IP.
cp /var/www/provisioning/htdocs/Algo/init.cfg.sample /var/www/provisioning/htdocs/Algo/init.cfg
== 4. Update the Algo firmware ==
Unfortunately, the Algo firmware update is a manual process:
*MENU System > Maintenance > Upgrade to New Firmware
**Method: From URL
**Upgrade URL: http://<IP or FQDN of provisioning>/Algo/algo-8180-2.4.fw
**Click Upgrade button
== 5. Configure the Algo 8180 to connect to the provisioning server ==
Unfortunately, the DHCP option 66 does not seem to work in our testing. So, you must manually configure the Algo to connect to the provisioning server. Once you get the Algo device connected to the network, follow these steps:
*MENU Advanced Settings > Provisioning
**Provisioning Mode: Enabled
**Server Method: Static
**Static Server: Enter the IP address or FQDN of the provisioning server
**Download Method: HTTP
**Config Download Path: Algo
**Firmware Download Path: Algo

SIP Provisioning On Alpine Linux

2015-06-09T14:21:00Z

Ttrask: Add link to Algo instructions

{{Draft}}
= Overview =
This page describes how to install a basic provisioning server for SIP devices based upon Postgresql and the ACF web interface. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install packages ==
Here are the basic packages for the provisioning functionality:
apk add acf-provisioning acf-postgresql acf-lighttpd
In addition, you can add the firmware packages for the SIP devices you want to support:
apk add acf-provisioning-cisco acf-provisioning-linksys acf-provisioning-polycom acf-provisioning-snom
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM. You can use the following command: apk fetch --quiet --stdout acf-provisioning-polycom | tar -C / -zvx}}

== 3. Configure Lighttpd ==
Lighttpd is used to provide the HTTP provisioning interface for the SIP devices. The provisioning package contains a sample configuration that can be used for lighttpd:
mv /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig
ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf
Modify mod_cgi.conf to treat CGI scripts as shell scripts, rather than perl:
sed -i 's~/usr/bin/perl"$~"~' /etc/lighttpd/mod_cgi.conf
Start the server:
/etc/init.d/lighttpd start

== 4. Start Postgresql ==
The device parameter details are stored in a Postgresql database. We can use the default configuration, so we just start the service:
/etc/init.d/postgresql start

== 5. Point your SIP device to the new server for provisioning ==
Instructions for various manufacturers are included on separate pages:
*[[Algo 8180 Provisioning With ACF]]

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).

[[Category:ACF]]

Algo 8180 Provisioning With ACF

2015-06-09T14:04:20Z

Ttrask: First cut

SIP Provisioning On Alpine Linux

2015-06-01T19:36:38Z

Ttrask: Minor fix

{{Draft}}
= Overview =
This page describes how to install a basic provisioning server for SIP devices based upon Postgresql and the ACF web interface. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install packages ==
Here are the basic packages for the provisioning functionality:
apk add acf-provisioning acf-postgresql acf-lighttpd
In addition, you can add the firmware packages for the SIP devices you want to support:
apk add acf-provisioning-cisco acf-provisioning-linksys acf-provisioning-polycom acf-provisioning-snom
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM. You can use the following command: apk fetch --quiet --stdout acf-provisioning-polycom | tar -C / -zvx}}

== 3. Configure Lighttpd ==
Lighttpd is used to provide the HTTP provisioning interface for the SIP devices. The provisioning package contains a sample configuration that can be used for lighttpd:
mv /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig
ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf
Modify mod_cgi.conf to treat CGI scripts as shell scripts, rather than perl:
sed -i 's~/usr/bin/perl"$~"~' /etc/lighttpd/mod_cgi.conf
Start the server:
/etc/init.d/lighttpd start

== 4. Start Postgresql ==
The device parameter details are stored in a Postgresql database. We can use the default configuration, so we just start the service:
/etc/init.d/postgresql start

== 5. Point your SIP device to the new server for provisioning ==

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).

[[Category:ACF]]

SIP Provisioning On Alpine Linux

2015-06-01T16:53:40Z

Ttrask: Draft of new document for seting up provisioning server

{{Draft}}
= Overview =
This page describes how to install a basic provisioning server for SIP devices based upon Postgresql and the ACF web interface. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install packages ==
Here are the basic packages for the provisioning functionality:
apk add acf-provisioning acf-postgresql acf-lighttpd
In addition, you can add the firmware packages for the SIP devices you want to support:
apk add acf-provisioning-cisco acf-provisioning-linksys acf-provisioning-polycom acf-provisioning-snom
{{Note|If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM. You can use the following command: apk fetch --quiet --stdout acf-provisioning-polycom | tar -C / -zvx}}

== 3. Configure Lighttpd ==
Lighttpd is used to provide the HTTP provisioning interface for the SIP devices. The provisioning package contains a sample configuration that can be used for lighttpd:
mv /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig
ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf
Modify mod_cgi.conf to treat CGI scripts as shell scripts, rather than perl:
sed -i 's~/usr/bin/perl"$~"~' /etc/lighttpd/mod_cgi.conf
Start the server:
/etc/init.d/lighttpd start

== 4. Start Postgresql ==
The device parameter details are stored in a Postgresql database. We can use the default configuration, so we just start the service:
/etc/init.d/postgresql start

== 5. Point your SIP device to the new server for provisioning ==

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).

[[Category:ACF]]

Freeswitch Voicemail On Alpine Linux

2015-05-21T18:00:07Z

Ttrask: Bad paths fixed for Alpine Linux 3.2 and later

= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items are not needed for Alpine Linux 3.2 or later. They are needed on earlier versions due to bad default paths in the freeswitch package.}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf
Change the ACF voicemail domain to match the domain from the sample config. You should use the IP address of your voicemail server, as this is what the sample config uses.
sed -i /^domain=/d /etc/freeswitchvmail.conf
echo "domain=IPADDRESS" >> /etc/freeswitchvmail.conf

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

= Other Features =
== Using PostgreSQL ==
Freeswitch-1.2.5 and acf-freeswitch-vmail-0.5.0 fully support Postgresql as the voicemail database. These versions are available in Alpine Linux 3.2 and later. To configure it:
=== 1. Install Postgresql ===
apk add postgresql acf-postgresql
=== 2. Setup and Start Postgresql ===
rc-update add postgresql
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
=== 3. Create the Database ===
psql -U postgres -c "CREATE DATABASE voicemail"
=== 4. Stop Freeswitch ===
/etc/init.d/freeswitch stop
{{Note|Freeswitch does not always stop properly. You might need to run 'ps ax' to find the process and 'kill' it. Running '/etc/init.d/freeswitch zap' might also be necessary.}}
=== 5. Configure Freeswitch and acf-freeswitch-vmail ===
Edit /etc/freeswitch/autoload_configs/voicemail.conf.xml to set the odbc-dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
<param name="odbc-dsn" value="pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''" />
Edit /etc/freeswitchvmail.conf and set the dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
dsn=pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''
=== 6. Restart Freeswitch ===
/etc/init.d/freeswitch start

[[Category:ACF]]

Freeswitch Voicemail On Alpine Linux

2015-04-27T20:22:13Z

Ttrask:

= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items should not be needed, but are caused by bad default paths in the freeswitch package}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf
Change the ACF voicemail domain to match the domain from the sample config. You should use the IP address of your voicemail server, as this is what the sample config uses.
sed -i /^domain=/d /etc/freeswitchvmail.conf
echo "domain=IPADDRESS" >> /etc/freeswitchvmail.conf

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

= Other Features =
== Using PostgreSQL ==
Freeswitch-1.2.5 and acf-freeswitch-vmail-0.5.0 fully support Postgresql as the voicemail database. These versions are available in Alpine Linux 3.2 and later. To configure it:
=== 1. Install Postgresql ===
apk add postgresql acf-postgresql
=== 2. Setup and Start Postgresql ===
rc-update add postgresql
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
=== 3. Create the Database ===
psql -U postgres -c "CREATE DATABASE voicemail"
=== 4. Stop Freeswitch ===
/etc/init.d/freeswitch stop
{{Note|Freeswitch does not always stop properly. You might need to run 'ps ax' to find the process and 'kill' it. Running '/etc/init.d/freeswitch zap' might also be necessary.}}
=== 5. Configure Freeswitch and acf-freeswitch-vmail ===
Edit /etc/freeswitch/autoload_configs/voicemail.conf.xml to set the odbc-dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
<param name="odbc-dsn" value="pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''" />
Edit /etc/freeswitchvmail.conf and set the dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
dsn=pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''
=== 6. Restart Freeswitch ===
/etc/init.d/freeswitch start

[[Category:ACF]]

Freeswitch Voicemail On Alpine Linux

2015-04-27T13:41:38Z

Ttrask: And commands to switch to postgresql instead of sqlite

= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items should not be needed, but are caused by bad default paths in the freeswitch package}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf
Change the ACF voicemail domain to match the domain from the sample config. You should use the IP address of your voicemail server, as this is what the sample config uses.
sed -i /^domain=/d /etc/freeswitchvmail.conf
echo "domain=IPADDRESS" >> /etc/freeswitchvmail.conf

= ACF Web interface =
You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

= Other Features =
== Using PostgreSQL ==
Freeswitch-1.2.5 and acf-freeswitch-vmail-0.5.0 fully support Postgresql as the voicemail database. These versions are available in Alpine Linux 3.2 and later. To configure it:
=== 1. Install Postgresql ===
apk add postgresql acf-postgresql
=== 2. Setup and Start Postgresql ===
rc-update add postgresql
/etc/init.d/postgresql setup
/etc/init.d/postgresql start
=== 3. Create the Database ===
psql -U postgres -c "CREATE DATABASE voicemail"
=== 4. Stop Freeswitch ===
/etc/init.d/freeswitch stop
{{Note|Freeswitch does not always stop properly. You might need to run 'ps ax' to find the process and 'kill' it. Running '/etc/init.d/freeswitch zap' might also be necessary.}}
=== 5. Configure Freeswitch and acf-freeswitch-vmail ===
Edit /etc/freeswitch/autoload_configs/voicemail.conf.xml to set the odbc-dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
<param name="odbc-dsn" value="pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''" />
Edit /etc/freeswitchvmail.conf and set the dsn param to "pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''"
dsn=pgsql://hostaddr=127.0.0.1 dbname=voicemail user=postgres password= options=''
=== 6. Restart Freeswitch ===
/etc/init.d/freeswitch start

Freeswitch Voicemail On Alpine Linux

2015-04-26T19:48:18Z

Ttrask: Fix command for /etc/freeswitchvmail.conf because it does not exist at first

Freeswitch Voicemail On Alpine Linux

2015-04-13T13:43:57Z

Ttrask: Fixed domain config issue

Freeswitch Voicemail On Alpine Linux

2015-04-12T20:49:57Z

Ttrask: Fixed packages for alpine 3.0 - 3.2

{{Draft}}
= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, and the future 3.2.

{{Note|While dialing 4000 to get to the voicemail IVR works, and logging in as ACF-managed voicemail users works, new voicemail messages are not showing up. Not sure why yet.}}

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>
{{Note|These following items should not be needed, but are caused by bad default paths in the freeswitch package}}
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf

= ACF Web interface =
You can now browse to https://<ip address> to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

Freeswitch Voicemail On Alpine Linux

2015-04-11T01:20:41Z

Ttrask: Current status

{{Draft}}
= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 3.2.

* Alpine 3.2 - dialing 4000 does not list voicemails, voicemail actions through ACF don't work (nc doesn't exit)
* Alpine 3.1 -
* Alpine 3.0 - dialing 4000 does not list voicemails, voicemail actions through ACF don't work (nc doesn't exit)
* Alpine 2.7 - dialing 4000 does not list voicemails, downloading works fine

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf

= ACF Web interface =
You can now browse to https://<ip address> to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

Freeswitch Voicemail On Alpine Linux

2015-04-10T21:14:56Z

Ttrask: First cut

{{Draft}}
= Overview =
This page describes how to install a basic voicemail server based upon Freeswitch including a web interface based upon ACF. It is built and tested on Alpine Linux 3.2.

= Setup Procedure=
== 1. Configure the machine ==
Install and configure a basic Alpine Linux server with the ACF web interface.
setup-alpine
setup-acf

== 2. Install Freeswitch ==
apk add freeswitch freeswitch-sounds-en-us-callie-8000 freeswitch-flite acf-freeswitch acf-freeswitch-vmail

== 3. Configure Freeswitch ==
We will use the Freeswitch sample configuration for the purposes of this document. It is not recommended to use this config in production, but it will allow us to quickly get voicemail up and running. Rather than installing the package, we will use apk to fetch the files.
apk fetch --quiet --stdout freeswitch-sample-config | tar -C / -zvx
Modify the default password to avoid warnings and delays (obviously, you can choose something other than 12345 if you want)
sed -i s/"default_password=1234"/"default_password=12345"/ /etc/freeswitch/vars.xml
Fix the voicemail storage directory in ''/etc/freeswitch/autoload_configs/voicemail.conf.xml'' to point to ''/var/lib/freeswitch/voicemail''
<param name="storage-dir" value="/var/lib/freeswitch/voicemail"/>
Set the sounds directory in ''/etc/freeswitch/vars.xml'' by adding the following line:
<X-PRE-PROCESS cmd="set" data="sounds_dir=/usr/share/freeswitch/sounds"/>
Use Freeswitch XML curl to call into ACF to determine voicemail accounts. To do so, edit ''/etc/freeswitch/autoload_configs/xml_curl.conf.xml'' and add the following bindings:
<binding name="voicemaildialplan">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdialplanxml" bindings="dialplan"/>
</binding>
<binding name="voicemaildirectory">
<param name="gateway-url" value="https://127.0.0.1/cgi-bin/acf/freeswitch-vmail/vmail/processdirectoryxml" bindings="directory"/>
</binding>
And modify ''/etc/freeswitch/autoload_configs/modules.conf.xml'' to load the mod_xml_curl module
<load module="mod_xml_curl"/>

== 4. Start Freeswitch ==
Start Freeswitch and add it to the default runlevel.
rc-update add freeswitch
/etc/init.d/freeswitch start
You should now be able to dial into Freeswitch voicemail by registering a SIP user agent to freeswitch (user=1000-1019, password=12345 as defined above) and directing a SIP call to any of the other extensions between 1000 and 1019, or the extension 4000. For each voicemail account, the default password is the same as the extension. For more details on this, please refer to Freeswitch documentation. Please keep in mind that these extensions and voicemail are part of the sample config and are not managed by ACF. We will add ACF-managed voicemail accounts below.

== 5. Configure acf-freeswitch-vmail ==
Add the voicemail authenticator to the ACF configuration. This will allow voicemail users to log into ACF to check their voicemail.
echo "authenticator = authenticator-freeswitch-vmail.lua,authenticator-plaintext" >> /etc/acf/acf.conf

= ACF Web interface =
You can now browse to https://<ip address> to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).
== Users ==
The Voicemail | Users tab will display all of the voicemail users that are managed through the ACF web interface. At the start, this will be empty. When you create Users in the ACF, it will modify the freeswitch dialplan and directory (using xml_curl) to allow these users to receive and retrieve voicemail. It will also allow these users log into the ACF interface to check their voicemail and modify voicemail settings. The password defined here will control both ACF and IVR access.
== Voicemail ==
The Voicemail | Voicemail tab will allow you to view, listen to, download, forward, and delete voicemail messages.
== Config ==
The Voicemail | Config tab allows administrators to modify the acf-freeswitch-vmail configuration.
== Settings ==
The Voicemail | Settings tab allows voicemail users to modify their settings.

= Demonstration =
We are now ready to create voicemail accounts with ACF. The freeswitch sample config creates a fairly full dialplan and we do not want to stomp on any of its features, so we will demonstrate accounts in the 2100 - 2199 range, which is unused.
# Dial extension 2100 to verify what happens when an unsupported extension is called
# Logged into ACF as root, create a voicemail user with extension 2100 and some password
# Dial extension 2100 again to verify that you can now leave a voicemail for extension 2100
# Dial extension 4000 and log in as user 2100 with the password you defined above to listen to the message
# Log out of ACF as root and log in again as user 2100 with the password you defined above to view your message

ACF how to write

2015-03-09T19:34:23Z

Ttrask: Update to latest style

=How to Write an ACF=

For some examples please see the Web Configuration Framework projects in the Alpine Linux git repository

http://git.alpinelinux.org/

*acf-unbound - a simple ACF to control a service
*acf-awall - a slightly more complicated ACF for a firewall
*acf-provisioning - a complicated database application based on ACF
*...

==From <nil> to a running ACF example application==

===Step 1 - The Programming Language===
* ACF uses lua as its programming language. Have a look at [http://www.lua.org/ lua.org] before starting.

===Step 2 - The Application Environment===
* Setup the ACF web application by running ''setup-acf''

===Step 3 - Create A Development Directory===
* In your user home create a directory for your application (e.g. mkdir ~/myapp)
* And cd into it (e.g. cd ~/myapp)

===Step 4 - MVC, How Does It Affect My Coding?===
ACF is an MVC based framework. What does this mean to you? Your application is separated into three layers: Model, View, Controller - each of which may have one or more files.
* Controller: The event dispatcher. Most of the controller functionality is handled by the ACF mvc.lua code and some standard controllers (such as acf_www-controller.lua or acf_cli-controller.lua). For the controller layer of your new ACF package, you must export one lua function per action in a lua module named 'myapp-controller.lua'. The ACF controller code will interpret the user interaction to load your new controller and fire the appropriate action - the same-named function in your controller will be called.
* View: The view layer defines what your application will look like. For most actions, such as forms, your application can use the built-in automatic view generation. For others, you can link to standard views which are included in the acf-core package. For other actions, such as lists of data, you may create view files, each presenting a dynamic HTML page with only as much code as necessary to display the data you receive from the controller.
* Model: The 'real work' is done in the Model (e.g. modifying config files, starting/stopping services etc.). Each action exported by your controller will call into model functions to retrieve data and carry out actions.

===Step 5 - The Example Files To Start With===
Now let us have a look at the files we need to place into our application directory:

* config.mk
* Makefile
* myapp-controller.lua
* myapp-model.lua
* myapp.roles
* myapp.menu

'''config.mk:'''
For use with the Makefile. Just copy/paste it. We will look at it later.
prefix=/usr
datadir=${prefix}/share
sysconfdir=${prefix}/etc
localstatedir=${prefix}/var
acfdir=${datadir}/acf
wwwdir=${acfdir}/www
cgibindir=${acfdir}/cgi-bin
appdir=${acfdir}/app
acflibdir=${acfdir}/lib
sessionsdir=${localstatedir}/lib/acf/sessions

'''Makefile:'''

The Makefile is called to install our ACF application so that we can see it working.
APP_NAME=myapp
PACKAGE=acf-$(APP_NAME)
VERSION=0.1

APP_DIST= \
myapp* \

EXTRA_DIST=README Makefile config.mk

DISTFILES=$(APP_DIST) $(EXTRA_DIST)

TAR=tar

P=$(PACKAGE)-$(VERSION)
tarball=$(P).tar.bz2
install_dir=$(DESTDIR)/$(appdir)/$(APP_NAME)

all:
clean:
rm -rf $(tarball) $(P)

dist: $(tarball)

install:
mkdir -p "$(install_dir)"
cp -a $(APP_DIST) "$(install_dir)"

$(tarball): $(DISTFILES)
rm -rf $(P)
mkdir -p $(P)
cp $(DISTFILES) $(P)
$(TAR) -jcf $@ $(P)
rm -rf $(P)

# target that creates a tar package, unpacks is and install from package
dist-install: $(tarball)
$(TAR) -jxf $(tarball)
$(MAKE) -C $(P) install DESTDIR=$(DESTDIR)
rm -rf $(P)

include config.mk

.PHONY: all clean dist install dist-install

'''myapp-controller.lua:'''
-- the myapp controller
local mymodule = {}

mymodule.default_action = "myaction"

mymodule.myaction = function(self)
-- self.clientdata contains the user data
-- self.model points to our model
-- use the helper function to implement our form
return self.handle_form(self, self.model.getdata, self.model.setdata, self.clientdata, "Submit", "Edit data", "Data Submitted")
end

return mymodule

'''myapp-model.lua:'''
-- acf model for myapp
local mymodule = {}

local cfgfile = "/tmp/myfile"

-- This function returns a cfe (table of values) containing the file's
-- value as a string. If the file does not exist, we'll
-- simply return "" (an empty string, but NOT nil)
mymodule.getdata = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Data" })
retval.value.data = cfe({ type="longtext", label="Data" })

local fileptr = io.open(cfgfile, "r")
if fileptr ~= nil then
retval.value.data.value = fileptr:read("*a") or ""
fileptr:close()
end

return retval
end

-- This function will write new contents into our file
-- The newdata parameter receives the same cfe as returned by getdata, now with the user data filled in
mymodule.setdata = function(self, newdata, action)
fileptr = io.open( cfgfile, "w+" )
if fileptr ~= nil then
fileptr:write(newdata.value.data.value)
fileptr:close()
else
newdata.errtxt = "Failed to save data"
end
return newdata
end

return mymodule

'''myapp.roles:'''
GUEST=myapp:myaction

'''myapp.menu:'''
# Cat Group Tab Action
Test MyApp MyAction myaction

===Step 6 - What Does It Do?===
This program just displays a <textarea> box and a "Submit" button. The user can enter text that is saved into a file once he presses "Submit".

====In Depth====
Now let us have a closer look at the different files' contents:

=====myapp-controller.lua=====
The controller is an event dispatcher. So, here you define all the actions that the user can call or that are defined in the menu. Each action is a separate function that will receive ''self'' as the only parameter.

In our case the action is ''myaction'' - a simple form.

This function can call the ''model's'' functions to update and/or retrieve data (e.g. self.model.getdata()).

Anything that this function returns will be passed on to the ''view''

=====myapp-model.lua=====
The functions defined in here can be accessed by the controller to update/set/retrieve data, start/stop services, basically do any 'real work'.

In our case, we have implemented the getdata/setdata functions required for a form.

The getdata function receives a copy of 'self', a clientdata table, and a string containing the submit action. It will generate a 'CFE' table defining the form and including the current data.

The setdata function is only called when the form is submitted, and it receives a copy of 'self' and the updated form 'CFE' now containing the submitted data. The setdata function will attempt to perform the action, returning the same form 'CFE'. If there is an error, it will fill in the errtxt field of the 'CFE'.

=====myapp.roles=====
This file determines which users have access to which controllers and views. A separate ''roles'' file is generally defined for each ACF. The format of the file is as follows:
group=controller:action[,controller:action]
Each line defines controller:action combinations that are permitted for a particular group. '''GUEST''' is a special group to which all users, including anonymous users, are members.

=====myapp.menu=====
In this file you define:
* '''The Category''' in which a menu entry for your program will appear
* '''The Group''' menu name under Category for this controller
* '''The Tab''' name on the controller page
* '''The Action''' with-in your controller that will be called once the user clicks on the menu entry or tab defined by Category, Group, and Tab.

===Step 7 - How To Get It Going?===
Once you have completed all the above mentioned steps, go on with:
* sudo make install (this will install your app)
* point your browser to https://ip-of-your-dev-host/

===More Info===
====Where is the View?====
The above example does not contain any code for a view. So, how is the action getting displayed?

For every action that you define in myapp-controller.lua, you can define a separate view file named: myapp-''action''-html.lsp

If there is no view file for a specific action, the application will look for a generic view file for the controller named: myapp-html.lsp

If that file does not exist, the ACF controller will attempt to display the 'CFE' using the built-in library functions. This works well for forms, and is what allows us to display our view here.

Here is a ''view'' file that displays our action using the built-in library functions. It looks exactly the same as when no view exists.

'''myapp-myaction-html.lsp:'''
<%
local form, viewlibrary, page_info, session = ...
htmlviewfunctions = require("htmlviewfunctions")

htmlviewfunctions.displayitem(form, page_info)
%>

The view receives the data to be displayed from the ''controller''. The view has access to the table returned by the controller action along with a helper library, a table of page information, and the session data ''(see the second line)''. The view can also load other libraries, but it should not directly access the ''controller'', ''model'', or any global variables.

====How to exchange data between model-view-controller?====
To exchange data between model, view, and controller ACF uses ''Configuration Framework Entities (CFEs)''.

Please see [[ACF_core_principles]] for further details on CFEs.

[[Category:ACF]]

ACF mvc.lua example

2015-03-09T14:59:12Z

Ttrask: Minor changes

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an Alpine Linux box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes the form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.set_hostname, self.clientdata, "Edit", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and set the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Hostname" })

-- Warning - io.popen has security risks, never pass user data to io.popen
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.value.hostname = cfe({ value=n, label="Hostname" })

return retval
end

-- Set the hostname from the value contained in the cfe created by get_hostname
mymodule.set_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be 16 characters or less"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is valid, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
-- Warning - io.popen has security risks, never pass user data to io.popen
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to set hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.set_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the first case read the existing hostname and the second case updated it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is written to stdout.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions. For handling forms and user input, the application will call the action once to retrieve the form cfe, then fill in the desired input values into the cfe and call the action again to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
Todo

=== Use the New method ===
Todo

{{Obsolete}}
4. Create a dispatch wrapper program, named '''helloworld.lua''' in the current directory:

-- Simple CLI based mvc application

-- this is to get around having to store
-- the config file in /etc/helloworld/helloworld.conf
ENV={}
ENV.HOME="."

-- load the module
require("mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("helloworld")

-- create an application container
APP=MVC:new("app")

-- dispatch the request
APP.clientdata.hostname=arg[2]
APP:dispatch( "", "hostname", (arg[1] or ""))

-- destroy the mvc objects
APP:destroy()
MVC:destroy()

This application loads the "mvc.lua" framework, creates an mvc "object" named "MVC", then reads the helloworld.conf file to find out where the app dir is (helloworld/app/). It then loads the '''app-controller.lua''' into a new "application level" object named '''APP'''. Finally, it sets the clientdata and dispatches the hostname-controller/model pair.

5. Test the application:
# hostname
Alpine
# lua helloworld.lua no-such-function foo
The following unhandled application error occured:

controller: "hostname" does not have a "no-such-function" action.
# hostname
Alpine

# hostname
Alpine
# lua helloworld.lua update Alline
Your controller and application did not specify a view resolver.
The MVC framework has no view available. sorry.
# hostname
Alline

Note in the second case the hostname ''was'' changed, although the application does not know how to report success.

== Create a view resolver and view formatter ==

The view resolver is a function that returns a function that processes the view. The returned function receives input from the controller and generates the output to be displayed.

We will build a very simple view resolver and view processor for our application. Add this to the end of '''helloworld/app/hostname-controller.lua'''

local private = {}

private.view = function (f)
if (f.msg) then
print( (f.value or "") .. " is not a valid hostname ")
else
print ("Hostname is currently " .. f.value )
end
end

view_resolver = function (self)
return private.view
end

Now we can test:

# lua helloworld.lua update "1 2 3"
1 2 3 is not a valid hostname
# lua helloworld.lua update
is not a valid hostname
# lua helloworld.lua update Alpine
Hostname is currently Alpine

But we have two problems:

1. We now have to make a view resolver and view function for every controller. If we add a ''date'' setting controller, we'll have to make a view resolver and view function for it, and so on.

2. Perhaps more importantly, view_resolver is now an "action" in our appliction. Recall that invalid actions are captured, but try this:

# lua helloworld.lua no_such_action Alpine
The following unhandled application error occured:

controller: "hostname" does not have a "no_such_action" action.

# lua helloworld.lua view_resolver Alpine
The following unhandled application error occured:

./helloworld/app/hostname-controller.lua:27: attempt to index local 'f' (a function value)
stack traceback:
./helloworld/app/hostname-controller.lua:27: in function 'viewfunc'
./mvc.lua:139: in function <./mvc.lua:90>
[C]: in function 'xpcall'
./mvc.lua:90: in function 'dispatch'
helloworld.lua:23: in main chunk
[C]: ?

Because view_resolver is an action in the worker table, the '''mvc.lua''' runs it; but it returns a function, not a table, and causes an unhandled exception in the view.

== Move the view resolver to the application level ==

The solution to both problems is to move the view resolver and the view function out of the controller's worker table, into the next higher level, in this case, the application's worker table:

1. Delete the private.view and view_resolver functions from '''helloworld/app/hostname-controller.lua'''

2. Add the following to '''helloworld/app/app-controller.lua'''

local private = {}

private.view = function ( controller, action, viewtable )
io.write(string.format("Controller: %s Action: %s\n",
controller or "", action or ""))
io.write ("Returned a table with the following values:\n")

for k,v in pairs(viewtable) do
io.write(string.format("%s\t%s\n", k, v))
end
end

view_resolver = function (self)
return function (viewtable)
return private.view (self.conf.controller, self.conf.action, viewtable)
end
end

This creates a more "generic" view, but one that will work for any controller - not just '''hostname'''.

Now things work as they should:

# lua helloworld.lua update "one two"
Controller: hostname Action: update
Returned a table with the following values:
value one two
type string
msg Hostname can contain alphanumerics only

# lua helloworld.lua view_resolver "Alpine"
The following unhandled application error occured:

controller: "hostname" does not have a "view_resolver" action.

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ACF acf www example

2015-02-15T14:29:19Z

Ttrask: Mark obsolete

{{ Obsolete }}
= Set the hostname with a web interface =

In this example we will use the hostname-model.lua and hostname-controller.lua from the previous example to set the hostname using the acf web interface.

For this example, we will assume you have root access on the linux box you are running on (preferably an alpine box!)

== Use the existing code ==

We should have '''mvc.lua'' in the current directory, with the controller and model in ''helloworld/app'' The Controller and Model look the same as the end of the mvc.lua example, except we've taken out the on_load, pre_exec, post_exec, and on_unload methods.

=== helloworld/app/hostname-controller.lua ===
-- hostname controller code

module ( ... , package.seeall )

create = function (self )
return self.model.update(self.clientdata.hostname)
end

read = function (self)
return self.model.read()
end

update = create

delete = function (self )
self.clientdata.hostname=""
return self.worker:create()
end

=== helloworld/app/hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
module ( ..., package.seeall )

-- All functions return a table with
-- A value, the type of the value, and a message if there was an error

local hosttype={ type="string" }

update= function ( name )
-- Check to make sure the name is valid

if (name == nil) then
hosttype.msg = "Hostname cannot be nil"
elseif (#name > 16) then
hosttype.msg = "Hostname must be less than 16 chars"
elseif (string.find(name, "[^%w%_%-]")) then
hosttype.msg = "Hostname can contain alphanumerics only"
end

-- If it is, set the hostname
if (hosttype.msg == nil ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(name .. "\n")
f:close()
end
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
return read()
-- Otherwise, return the error message
else
hosttype.value = name
return hosttype
end
end

read= function ()
local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")
hosttype.value = n
return (hosttype)
end

== Get and configure ACF ==

1. Grab a copy of all the acf code and support libraries from svn and copy into an "/usr/share/acf" directory

svn export svn://svn.alpinelinux.org/acf/core/trunk /usr/share/acf

2. Copy the acf.conf file to /etc/acf

cp /usr/share/acf/acf.conf /etc/acf/acf.conf

3. Start the web server

You'll need haserl, lua, and mini_httpd installed to run acf. If not already done, please install them.

Start mini_httpd (by hand for now)

mini_httpd -d /usr/share/acf/www -c 'cgi-bin/**' start

4. Move your hostname model and controller

mkdir /usr/share/acf/app/sample
mv helloworld/app/hostname-* /usr/share/acf/app/sample/

5. Create a new view template, which is a "lua server page" Create the file as ''/usr/share/acf/app/sample/hostname-html.lsp''

<? local form = ... ?>
<h1>Hostname</h1>

<form action="update" method=post>
<p>The Hostname is now <input name=hostname value="<?= form.value ?>"</p>

<p>input type=submit value=Submit></p>
</form>

6. Create a new roles file, which gives all users permission to access your actions. Create the file as ''/usr/share/acf/app/sample/hostname.roles''

GUEST=hostname/read,hostname/update

== Try the app ==

point your browser to your host/cgi-bin/acf/sample/hostname/read

You should now be able to update the hostname using the web interface, and your ''existing'' model and controller.

[[Category:ACF]]

Generating SSL certs with ACF

2015-01-30T20:32:42Z

Ttrask: Add examples of certificates for mini_httpd and openvpn

You need to create certificates for servers or remote persons. You might need an SSL cert for your web server running lighttpd or mini_httpd. You might use something like openvpn or racoon for your VPN services. Wouldn't it be nice to have some way to manage and view all the certs you have given to everyone? Revoke the certs? Review the certificate before you issue it?
Alpine, via ACF, has a nice web interface to use for this sort of job...

==Installation Process==
This will somewhat guide you through the process of creating this type of server. It is suggested to not host this on your VPN gateway, but use another machine to generate your certificates.

===Install Alpine ===
Link below to the standard document.

[[Installing_Alpine]]

=== Install and Configure ACF ===
Run the following command:
This will install the web front end to Alpine Linux, called ACF.

{{Cmd|/sbin/setup-acf}}

Install acf-openssl

{{Cmd|apk add acf-openssl}}

Browse to your computer https://ipaddr/

Login as root.

Click on the User Management tab and create yourself an account.

=== Acf-openssl ===

From the navigation bar on the left, under the Applications section, click the Certificate Authority link.

If you already have a CA that you would like to have the web interface manage you can upload it from the Status page (as a pfx).

From the Status tab, Click Configure(to remove most of the error messages).

If you do not have a CA, To generate a new CA certificate:
Click the Edit Defaults tab. Input the Items that will be needed for the CA and any other certs generated from it then Click Save.
Click the Status tab. Input values for the input boxes to generate a CA and click Generate.

== Generate a certificate with ACF ==
=== Request Form ===
Provided Fields:
* Country Name (2 letter abbreviation)
* Locality Name (e.g. city)
* Organization Name
* Common Name (eg, the certificate CN)
* Email Address
* Multiple Organizational Unit Name (eg, division)
* Certificate Type

A box has been set aside for adding Additional x509 Extensions formatted the same as if you were to fill out a section directly in openssl.cnf. Section would be
<tt>[v3_req]</tt>

You could put in here:
* subjectAltName ="IP:192.168.1.1"
* subjectAltName ="DNS:192.168.1.10"

Here is also where you would specify the CRL / OCSP distribution point, from where clients can query information:
* crlDistributionPoints=URI:http://whatever.com/whatever.crl

Once this form has been filled out and the password entered click submit.

=== View ===
Go to the View tab after you have the request form submitted. The view tab will show you pending requests for certificates. Also available from this tab are already approved requests (generated certs), revoked certs, and the CRL.

For a Pending request, make sure to review the cert before approving it. Once you have verified that all the information is correct, with no mis-types or spelling mistakes, Approve the request.

The file that will be generated can be downloaded from the ACF. Use the command lines below to extract the pkcs12 file into its part to begin using it.

=== Extract PFX certificate ===
To get the CA CERT

{{Cmd|openssl pkcs12 -in PFXFILE -cacerts -nokeys -out cacert.pem}}

To get the Private Key

{{Cmd|openssl pkcs12 -in PFXFILE -nocerts -nodes -out mykey.pem}}
Since this file contains the key without passsword protection, make sure to set restrictive permissions on this file.

To get the Certificate

{{Cmd|openssl pkcs12 -in PFXFILE -nokeys -clcerts -out mycert.pem}}

To get the Certificate and Private key in a single file (For lighttpd or mini_httpd for instance)

{{Cmd|openssl pkcs12 -in PFXFILE -nodes -out server.pem}}
Since this file contains the key without passsword protection, make sure to set restrictive permissions on this file.

To get the CA Chain (For lighttpd for instance)

{{Cmd|openssl pkcs12 -in PFXFILE -nokeys -cacerts -chain -out ca-certs.pem}}

Display the cert or key readable/text format

{{Cmd|openssl x509 -in mycert.pem -noout -text}}

==Examples==
===Replacing the ACF SSL cert===
By default, setup-acf uses mini_httpd with a self-signed certificate for serving ACF webpages. We can replace the self-signed certificate with one signed by our new CA.

Create a certificate of type 'ssl_server_cert' with appropriate settings (i.e. Common Name = server name)

Download the certificate pfx and upload it to the ACF server (remember, this is generally separate from the standalone Certificate Authority server)

Replace the mini_httpd server certificate
{{Cmd|openssl pkcs12 -in PFXFILE -nodes -out /etc/ssl/mini_httpd/server.pem}}

Restart mini_httpd
{{Cmd|/etc/init.d/mini_httpd restart}}

===Generating server and client certs for OpenVPN===
For OpenVPN use, we need a server certificate and one client certificate for each user. ACF can be used to generate all of them, including allowing users to request their own client certificates.

Generate a certificate of type 'ssl_server_cert' with appropriate settings for the OpenVPN server.

Copy the server certificate pfx to the OpenVPN server and extract the certificate using the commands above. Configuration of the OpenVPN server is beyond the scope here.

Create an ACF user account on the Certificate Authority server for each OpenVPN user. From the navigation bar, click on User Management under System. Click on Create. Create a user with CERT_REQUESTER role for each user. You could set the user Home to /openssl/openssl/read to default to showing that user's certificates.

Each user can request his own client certificate. Log in as the new user. Create a certificate request for a certificate of type 'ssl_client_cert' with appropriate settings.

You can view and approve the requested certificates as described above.

The user can then download and install the client certificate pfx on his OpenVPN client. Once again, this is beyond the scope of this document.

==Extras==
===OpenSSL command line to create your CA ===
The following command will need a password. Make sure to remember this.

{{Cmd|openssl genrsa -des3 -out server.key 2048}}

{{Cmd|openssl req -new -key server.key -out server.csr}}

{{Cmd|openssl rsa -in server.key. -out server.pem}}

{{Cmd|openssl x509 -req -days 365 -in server.csr -signkey server.pem -out cacert.pem}}

{{Cmd|mv server.pem /etc/ssl/private; mv cacert.pem /etc/ssl/}}

===Edits to /etc/ssl/openssl-ca-acf.cnf ===
Via the expert tab on ACF edit the openssl-ca-acf.cnf file. Something like subjectAltName can be added to be used by the certificates that you generate.

<tt>3.subjectAltName = Assigned IP Address </tt>

<tt>3.subjectAltName_default = 192.168.1.1/32</tt>

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

Generating SSL certs with ACF

2015-01-30T19:59:33Z

Ttrask: Cleanup / reorg

You need to create certificates for servers or remote persons. You might need an SSL cert for your web server running lighttpd or mini_httpd. You might use something like openvpn or racoon for your VPN services. Wouldn't it be nice to have some way to manage and view all the certs you have given to everyone? Revoke the certs? Review the certificate before you issue it?
Alpine, via ACF, has a nice web interface to use for this sort of job...

==Installation Process==
This will somewhat guide you through the process of creating this type of server. It is suggested to not host this on your VPN gateway, but use another machine to generate your certificates.

===Install Alpine ===
Link below to the standard document.

[[Installing_Alpine]]

=== Install and Configure ACF ===
Run the following command:
This will install the web front end to Alpine Linux, called ACF.

{{Cmd|/sbin/setup-acf}}

Install acf-openssl

{{Cmd|apk add acf-openssl}}

Browse to your computer https://ipaddr/

Login as root.

Click on the User Management tab and create yourself an account.

=== Acf-openssl ===

From the navigation bar on the left, under the Applications section, click the Certificate Authority link.

If you already have a CA that you would like to have the web interface manage you can upload it from the Status page (as a pfx).

From the Status tab, Click Configure(to remove most of the error messages).

If you do not have a CA, To generate a new CA certificate:
Click the Edit Defaults tab. Input the Items that will be needed for the CA and any other certs generated from it then Click Save.
Click the Status tab. Input values for the input boxes to generate a CA and click Generate.

== Generate a certificate with ACF ==
=== Request Form ===
Provided Fields:
* Country Name (2 letter abbreviation)
* Locality Name (e.g. city)
* Organization Name
* Common Name (eg, the certificate CN)
* Email Address
* Multiple Organizational Unit Name (eg, division)
* Certificate Type

A box has been set aside for adding Additional x509 Extensions formatted the same as if you were to fill out a section directly in openssl.cnf. Section would be
<tt>[v3_req]</tt>

You could put in here:
* subjectAltName ="IP:192.168.1.1"
* subjectAltName ="DNS:192.168.1.10"

Here is also where you would specify the CRL / OCSP distribution point, from where clients can query information:
* crlDistributionPoints=URI:http://whatever.com/whatever.crl

Once this form has been filled out and the password entered click submit.

=== View ===
Go to the View tab after you have the request form submitted. The view tab will show you pending requests for certificates. Also available from this tab are already approved requests (generated certs), revoked certs, and the CRL.

For a Pending request, make sure to review the cert before approving it. Once you have verified that all the information is correct, with no mis-types or spelling mistakes, Approve the request.

The file that will be generated can be downloaded from the ACF. Use the command lines below to extract the pkcs12 file into its part to begin using it.

=== Extract PFX certificate ===
To get the CA CERT

{{Cmd|openssl pkcs12 -in PFXFILE -cacerts -nokeys -out cacert.pem}}

To get the Private Key

{{Cmd|openssl pkcs12 -in PFXFILE -nocerts -nodes -out mykey.pem}}
Since this file contains the key without passsword protection, make sure to set restrictive permissions on this file.

To get the Certificate

{{Cmd|openssl pkcs12 -in PFXFILE -nokeys -clcerts -out mycert.pem}}

To get the Certificate and Private key in a single file (For lighttpd or mini_httpd for instance)

{{Cmd|openssl pkcs12 -in PFXFILE -nodes -out server.pem}}
Since this file contains the key without passsword protection, make sure to set restrictive permissions on this file.

To get the CA Chain (For lighttpd for instance)

{{Cmd|openssl pkcs12 -in PFXFILE -nokeys -cacerts -chain -out ca-certs.pem}}

Display the cert or key readable/text format

{{Cmd|openssl x509 -in mycert.pem -noout -text}}

==Extras==
===OpenSSL command line to create your CA ===
The following command will need a password. Make sure to remember this.

{{Cmd|openssl genrsa -des3 -out server.key 2048}}

{{Cmd|openssl req -new -key server.key -out server.csr}}

{{Cmd|openssl rsa -in server.key. -out server.pem}}

{{Cmd|openssl x509 -req -days 365 -in server.csr -signkey server.pem -out cacert.pem}}

{{Cmd|mv server.pem /etc/ssl/private; mv cacert.pem /etc/ssl/}}

===Edits to /etc/ssl/openssl-ca-acf.cnf ===
Via the expert tab on ACF edit the openssl-ca-acf.cnf file. Something like subjectAltName can be added to be used by the certificates that you generate.

<tt>3.subjectAltName = Assigned IP Address </tt>

<tt>3.subjectAltName_default = 192.168.1.1/32</tt>

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

Local APK cache

2014-07-02T13:19:14Z

Ttrask: Removed reference to yum and apt-get

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.

The cache is enabled by creating a symlink named ''/etc/apk/cache'' that points to the cache directory.

To enable local cache run: {{Cmd|setup-apkcache}}

= To enable Local Cache on releases prior v2.3 =
Alpine Linux version prior to v2.3 does not have the ''setup-apkcache'' tool so the symlink needs to be set up manually.

== To manually enable Local Cache on HDD install ==
If you've installed Alpine to your hard drive (as 'sys'), then create a cache dir and then an ''/etc/apk/cache'' symlink pointing to that dir:
{{Cmd|mkdir -p /var/cache/apk
ln -s /var/cache/apk /etc/apk/cache}}

You normally don't need apk cache on HDD 'sys' installs but it might be handy if you re-install from net to have the packages cached.

== To manually enable Local Cache on run-from-RAM installs ==

# 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 if available.

= 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 a {{Path|/etc/local.d/*.stop}} file:

{{Cat|/etc/local.d/cache.stop|#!/bin/sh
# 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.}}

{{Note|Custom shutdown commands were formerly added to a {{Path|/etc/conf.d/local}}; but that method is now deprecated.}}

[[Category:Package Manager]]

Alpine ACF Skins

2014-02-04T21:10:50Z

Ttrask: Ttrask moved page Alpine Skins to Alpine ACF Skins without leaving a redirect: Should have ACF in the title

= ACF Skins =

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

== Directory Structure ==

Sample skins are located in the /usr/share/acf/www/skins/ directory. User-modifiable skins can be added to the /etc/acf/skins/ directory. Each skin is located in its own subdirectory and contains one or more of the following files:
* 'skin'.css - the main CSS file for the skin
* 'skin'-ie.css - Internet Explorer-specific CSS file (loaded in addition to 'skin'.css)
* 'skin'.js - javascript file for the skin

=== Images ===

It is common for skins to include image files. Skin-specific image files should be located in the skin subdirectory. Please see the sample skins for how to include images.

The acf-skin package also includes a variety of [http://tango.freedesktop.org/Tango_Icon_Library tango] images located in the static/tango directory.

=== Templates ===

As of acf-core-0.15.1, skins can also include template files. The acf_www-controller will look in the following locations for skin-specific templates before searching /usr/share/acf:
* 'skindirectory'/template-'controller'-'action'-'viewtype'.lsp
* 'skindirectory'/template-'controller'-'viewtype'.lsp
* 'skindirectory'/template-'action'-'viewtype'.lsp
* 'skindirectory'/template-'viewtype'.lsp

For example, the acf_www-controller will check the following locations for action /acf-util/skins/read with viewtype 'html' while using skin 'wik':
* /usr/share/acf/www/skins/wik/template-skins-read-html.lsp
* /usr/share/acf/www/skins/wik/template-skins-html.lsp
* /usr/share/acf/www/skins/wik/template-read-html.lsp
* /usr/share/acf/www/skins/wik/template-html.lsp

== Sample Skins ==

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/

== How To Contribute ==

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)''

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

Alpine ACF Skins

2014-02-04T21:10:03Z

Ttrask: Initial cut with some content stolen from Alpine_Configuration_Framework_Design

ACF mvc.lua example

2013-10-03T03:48:34Z

Ttrask: Start on the MVC application section

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an alpine box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes for form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.update_hostname, self.clientdata, "Edit", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and update the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = {}

local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.hostname = cfe({ value=n, label="Hostname" })

return cfe({ type="group", value=retval, label="Hostname" })
end

-- Update the hostname from the value contained in the cfe created by get_hostname
mymodule.update_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be less than 16 chars"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to update hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.update_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the first case read the existing hostname and the second case updated it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==
You have two options for creating an MVC based application of your own.

1. Use the ''dispatch'' function. This is the method used by the web interface and the acf-cli application. The action to be dispatched is passed in a string format ''/prefix/controller/action'' and the input values are passed in as a clientinfo table. Output is written to stdout.

2. Use the ''new'' function to load the desired controller and then directly call the controller actions. For handling forms and user input, the application will call the action once to retrieve the form cfe, then fill in the desired input values into the cfe and call the action again to submit the form and perform the desired action. The MVC application is responsible for any user interaction and display of the results.

=== Use the Dispatch method ===
Todo

=== Use the New method ===
Todo

{{Obsolete}}
4. Create a dispatch wrapper program, named '''helloworld.lua''' in the current directory:

-- Simple CLI based mvc application

-- this is to get around having to store
-- the config file in /etc/helloworld/helloworld.conf
ENV={}
ENV.HOME="."

-- load the module
require("mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("helloworld")

-- create an application container
APP=MVC:new("app")

-- dispatch the request
APP.clientdata.hostname=arg[2]
APP:dispatch( "", "hostname", (arg[1] or ""))

-- destroy the mvc objects
APP:destroy()
MVC:destroy()

This application loads the "mvc.lua" framework, creates an mvc "object" named "MVC", then reads the helloworld.conf file to find out where the app dir is (helloworld/app/). It then loads the '''app-controller.lua''' into a new "application level" object named '''APP'''. Finally, it sets the clientdata and dispatches the hostname-controller/model pair.

5. Test the application:
# hostname
Alpine
# lua helloworld.lua no-such-function foo
The following unhandled application error occured:

controller: "hostname" does not have a "no-such-function" action.
# hostname
Alpine

# hostname
Alpine
# lua helloworld.lua update Alline
Your controller and application did not specify a view resolver.
The MVC framework has no view available. sorry.
# hostname
Alline

Note in the second case the hostname ''was'' changed, although the application does not know how to report success.

== Create a view resolver and view formatter ==

The view resolver is a function that returns a function that processes the view. The returned function receives input from the controller and generates the output to be displayed.

We will build a very simple view resolver and view processor for our application. Add this to the end of '''helloworld/app/hostname-controller.lua'''

local private = {}

private.view = function (f)
if (f.msg) then
print( (f.value or "") .. " is not a valid hostname ")
else
print ("Hostname is currently " .. f.value )
end
end

view_resolver = function (self)
return private.view
end

Now we can test:

# lua helloworld.lua update "1 2 3"
1 2 3 is not a valid hostname
# lua helloworld.lua update
is not a valid hostname
# lua helloworld.lua update Alpine
Hostname is currently Alpine

But we have two problems:

1. We now have to make a view resolver and view function for every controller. If we add a ''date'' setting controller, we'll have to make a view resolver and view function for it, and so on.

2. Perhaps more importantly, view_resolver is now an "action" in our appliction. Recall that invalid actions are captured, but try this:

# lua helloworld.lua no_such_action Alpine
The following unhandled application error occured:

controller: "hostname" does not have a "no_such_action" action.

# lua helloworld.lua view_resolver Alpine
The following unhandled application error occured:

./helloworld/app/hostname-controller.lua:27: attempt to index local 'f' (a function value)
stack traceback:
./helloworld/app/hostname-controller.lua:27: in function 'viewfunc'
./mvc.lua:139: in function <./mvc.lua:90>
[C]: in function 'xpcall'
./mvc.lua:90: in function 'dispatch'
helloworld.lua:23: in main chunk
[C]: ?

Because view_resolver is an action in the worker table, the '''mvc.lua''' runs it; but it returns a function, not a table, and causes an unhandled exception in the view.

== Move the view resolver to the application level ==

The solution to both problems is to move the view resolver and the view function out of the controller's worker table, into the next higher level, in this case, the application's worker table:

1. Delete the private.view and view_resolver functions from '''helloworld/app/hostname-controller.lua'''

2. Add the following to '''helloworld/app/app-controller.lua'''

local private = {}

private.view = function ( controller, action, viewtable )
io.write(string.format("Controller: %s Action: %s\n",
controller or "", action or ""))
io.write ("Returned a table with the following values:\n")

for k,v in pairs(viewtable) do
io.write(string.format("%s\t%s\n", k, v))
end
end

view_resolver = function (self)
return function (viewtable)
return private.view (self.conf.controller, self.conf.action, viewtable)
end
end

This creates a more "generic" view, but one that will work for any controller - not just '''hostname'''.

Now things work as they should:

# lua helloworld.lua update "one two"
Controller: hostname Action: update
Returned a table with the following values:
value one two
type string
msg Hostname can contain alphanumerics only

# lua helloworld.lua view_resolver "Alpine"
The following unhandled application error occured:

controller: "hostname" does not have a "view_resolver" action.

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ACF mvc.lua example

2013-09-30T16:19:16Z

Ttrask: Export the new action to the web interface

= Set the hostname with mvc.lua =

In this example we will create a simple hostname-setting command-line application using mvc.lua. Once the controller/model are built, you can use ''the same code'' to set the hostname via the web with a web-based application controller.

For this example, we will assume you have root access on the linux box you are running on (preferably an alpine box!)

== Get the mvc.lua module ==

Get the mvc.lua module from the git repository.

wget http://git.alpinelinux.org/cgit/acf-core/plain/lua/mvc.lua

== Create a model and controller ==

Create a file '''hostname-controller.lua''', defining the functions that an "end user" could run. We will only create one action, edithostname, which will be used to read and update the hostname. Since the action makes changes to the system, it naturally takes for form of a 'form':

=== hostname-controller.lua ===
-- Controller for editing hostname
local mymodule = {}

mymodule.edithostname = function (self)
return self.handle_form(self, self.model.get_hostname, self.model.update_hostname, self.clientdata, "Edit", "Edit Hostname", "Hostname Updated")
end

return mymodule

Create a file '''hostname-model.lua''', defining the model functions to get and update the hostname. We return a cfe table for each function including the form with the one entry for hostname:

=== hostname-model.lua ===
-- Model functions for retrieving / setting the hostname
local mymodule = {}

-- Create a cfe defining the form for editing the hostname and containing the current value
mymodule.get_hostname = function(self, clientdata)
local retval = {}

local f = io.popen ("/bin/hostname")
local n = f:read("*a") or "none"
f:close()
n=string.gsub(n, "\n$", "")

retval.hostname = cfe({ value=n, label="Hostname" })

return cfe({ type="group", value=retval, label="Hostname" })
end

-- Update the hostname from the value contained in the cfe created by get_hostname
mymodule.update_hostname = function(self, hostnameform, action)
local success = true

-- Check to make sure the name is valid
if (hostnameform.value.hostname.value == "") then
success = false
hostnameform.value.hostname.errtxt = "Hostname must not be blank"
elseif (#hostnameform.value.hostname.value > 16) then
success = false
hostnameform.value.hostname.errtxt = "Hostname must be less than 16 chars"
elseif (string.find(hostnameform.value.hostname.value, "[^%w%_%-]")) then
success = false
hostnameform.value.hostname.errtxt = "Hostname can contain alphanumerics only"
end

-- If it is, set the hostname
if ( success ) then
local f = io.open("/etc/hostname", "w")
if f then
f:write(hostnameform.value.hostname.value .. "\n")
f:close()
end
f = io.popen ("/bin/hostname -F /etc/hostname")
f:close()
else
hostnameform.errtxt = "Failed to update hostname"
end

return hostnameform
end

return mymodule

== Optionally test the model code (without mvc.lua) ==

If you want, you can create a '''test.lua''' script to validate the model code works on its own:

=== test.lua ===
require("mvc") -- Needed for cfe function definition
m=require("hostname-model")

local form = m.get_hostname()
form.value.hostname.value = arg[1] or ""
form = m.update_hostname(nil, form)

if form.errtxt then
print("FAILED: "..form.value.hostname.errtxt or form.errtxt)
end
form = m.get_hostname()
print(form.value.hostname.value)

You can then test this with:

#lua test.lua "Alpine"
Alpine

#lua test.lua "Invalid Name"
FAILED: Hostname can contain alphanumerics only
Alpine

== Add the package to the ACF framework ==

To make the model and controller work within the ACF mvc.lua framework, we must do several things.

1. Install the ACF core package:

apk add acf-core

Optionally, you can add the entire web-based ACF framework:

setup-acf

2. Modify the ACF configuration file to look in /etc/acf/app/ for additional packages. Edit the /etc/acf/acf.conf file to add the ''/etc/acf/app/'' directory to the ''appdir'' comma-separated list:

appdir=/etc/acf/app/,/usr/share/acf/app/

3. Move the model and controller to the new package directory. We will call the package "test":

mkdir -p /etc/acf/app/test
mv hostname-*.lua /etc/acf/app/test

4. Test the new package using the acf-cli application:

# acf-cli /test/hostname/edithostname
result = {}
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "Alpine"
# acf-cli /test/hostname/edithostname hostname=test submit=true
result = {}
result["descr"] = "Hostname Updated"
result["label"] = "Edit Hostname"
result["option"] = "Edit"
result["type"] = "form"
result["value"] = {}
result["value"]["hostname"] = {}
result["value"]["hostname"]["label"] = "Hostname"
result["value"]["hostname"]["type"] = "text"
result["value"]["hostname"]["value"] = "test"

Note that the first case read the existing hostname and the second case updated it. The output of the acf-cli application is a serialized version of the cfe form, which is good for testing but not too useful in real life.

== Enable the package in the ACF web interface ==

1. Add the web-based ACF framework:

setup-acf

2. Configure all users to have access to the new hostname action. Edit "/etc/acf/app/test/hostname.roles" file and add GUEST permission for the edithostname action:

echo "GUEST=hostname/edithostname" > /etc/acf/app/test/hostname.roles

The new action should now be visible by browsing to ''https://IP-of-host/cgi-bin/acf/test/hostname/edithostname''. Obviously you might want to reconsider providing GUEST access to this action, because this allows unauthenticated users to modify your hostname.

3. Add the new hostname action to the ACF menu. Edit "/etc/acf/app/test/hostname.menu" file and add a menu item:

echo "Test Hostname Edit edithostname" > /etc/acf/app/test/hostname.menu

You will need to log off from the ACF interface (or delete the session cookie) before the new menu item will be visible.

== Make an MVC based application ==

4. Create a dispatch wrapper program, named '''helloworld.lua''' in the current directory:

-- Simple CLI based mvc application

-- this is to get around having to store
-- the config file in /etc/helloworld/helloworld.conf
ENV={}
ENV.HOME="."

-- load the module
require("mvc")

-- create an new "mvc object"
MVC=mvc:new()

-- load the config file so we can find the appdir
MVC:read_config("helloworld")

-- create an application container
APP=MVC:new("app")

-- dispatch the request
APP.clientdata.hostname=arg[2]
APP:dispatch( "", "hostname", (arg[1] or ""))

-- destroy the mvc objects
APP:destroy()
MVC:destroy()

This application loads the "mvc.lua" framework, creates an mvc "object" named "MVC", then reads the helloworld.conf file to find out where the app dir is (helloworld/app/). It then loads the '''app-controller.lua''' into a new "application level" object named '''APP'''. Finally, it sets the clientdata and dispatches the hostname-controller/model pair.

5. Test the application:
# hostname
Alpine
# lua helloworld.lua no-such-function foo
The following unhandled application error occured:

controller: "hostname" does not have a "no-such-function" action.
# hostname
Alpine

# hostname
Alpine
# lua helloworld.lua update Alline
Your controller and application did not specify a view resolver.
The MVC framework has no view available. sorry.
# hostname
Alline

Note in the second case the hostname ''was'' changed, although the application does not know how to report success.

== Create a view resolver and view formatter ==

The view resolver is a function that returns a function that processes the view. The returned function receives input from the controller and generates the output to be displayed.

We will build a very simple view resolver and view processor for our application. Add this to the end of '''helloworld/app/hostname-controller.lua'''

local private = {}

private.view = function (f)
if (f.msg) then
print( (f.value or "") .. " is not a valid hostname ")
else
print ("Hostname is currently " .. f.value )
end
end

view_resolver = function (self)
return private.view
end

Now we can test:

# lua helloworld.lua update "1 2 3"
1 2 3 is not a valid hostname
# lua helloworld.lua update
is not a valid hostname
# lua helloworld.lua update Alpine
Hostname is currently Alpine

But we have two problems:

1. We now have to make a view resolver and view function for every controller. If we add a ''date'' setting controller, we'll have to make a view resolver and view function for it, and so on.

2. Perhaps more importantly, view_resolver is now an "action" in our appliction. Recall that invalid actions are captured, but try this:

# lua helloworld.lua no_such_action Alpine
The following unhandled application error occured:

controller: "hostname" does not have a "no_such_action" action.

# lua helloworld.lua view_resolver Alpine
The following unhandled application error occured:

./helloworld/app/hostname-controller.lua:27: attempt to index local 'f' (a function value)
stack traceback:
./helloworld/app/hostname-controller.lua:27: in function 'viewfunc'
./mvc.lua:139: in function <./mvc.lua:90>
[C]: in function 'xpcall'
./mvc.lua:90: in function 'dispatch'
helloworld.lua:23: in main chunk
[C]: ?

Because view_resolver is an action in the worker table, the '''mvc.lua''' runs it; but it returns a function, not a table, and causes an unhandled exception in the view.

== Move the view resolver to the application level ==

The solution to both problems is to move the view resolver and the view function out of the controller's worker table, into the next higher level, in this case, the application's worker table:

1. Delete the private.view and view_resolver functions from '''helloworld/app/hostname-controller.lua'''

2. Add the following to '''helloworld/app/app-controller.lua'''

local private = {}

private.view = function ( controller, action, viewtable )
io.write(string.format("Controller: %s Action: %s\n",
controller or "", action or ""))
io.write ("Returned a table with the following values:\n")

for k,v in pairs(viewtable) do
io.write(string.format("%s\t%s\n", k, v))
end
end

view_resolver = function (self)
return function (viewtable)
return private.view (self.conf.controller, self.conf.action, viewtable)
end
end

This creates a more "generic" view, but one that will work for any controller - not just '''hostname'''.

Now things work as they should:

# lua helloworld.lua update "one two"
Controller: hostname Action: update
Returned a table with the following values:
value one two
type string
msg Hostname can contain alphanumerics only

# lua helloworld.lua view_resolver "Alpine"
The following unhandled application error occured:

controller: "hostname" does not have a "view_resolver" action.

= mvc load & exec special functions =

The '''mvc.lua''' module has a provision for executing code on module load, prior to executing the controller's action, just after executing the controller's action, and on module unload.

This is done with the mvc table in the controller. To demonstrate, let's add a few functions to '''helloworld/app/app-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the app controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the app controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the app controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the app controller's on_unload function")
end

Now running our script shows when the functions get called:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the app controller's pre_exec function
This is the app controller's post_exec function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

We can add mvc functions to a specific controller, as well. Add this to '''helloworld/app/hostname-controller.lua'''

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
end

mvc.pre_exec = function (self)
print ("This is the hostname controller's pre_exec function")
end

mvc.post_exec = function (self)
print ("This is the hostname controller's post_exec function")
end

mvc.on_unload = function (self)
print ("This is the hostname controller's on_unload function")
end

And this happens:

# lua helloworld.lua update "Alpine"
This is the app controller's on_load function
This is the hostname controller's on_load function
This is the hostname controller's pre_exec function
This is the hostname controller's post_exec function
This is the hostname controller's on_unload function
Controller: hostname Action: update
Returned a table with the following values:
value Alpine
type string
This is the app controller's on_unload function

Note that both the ''app'' and ''hostname'' '''on_load''' and '''on_unload''' functions were run, but only the ''hostname'' '''pre_exec''' and '''post_exec''' functions ran. This is because the pre and post exec functions are run as part of the "action", and the '''dispatch''' function looks in the lowest-level controller for the pre/post_exec function. Since ''hostname'' now defines those functions, it runs them.

To run both the ''hostname'' and ''app'' pre_exec function, you must arrange for the ''hostname'' pre_exec function to call it's parent pre_exec:

mvc = {}
mvc.on_load = function (self, parent)
print ("This is the hostname controller's on_load function")
mvc.parent_pre_exec = parent.worker.mvc.pre_exec
end

mvc.pre_exec = function (self)
mvc.parent_pre_exec (self)
print ("This is the hostname controller's pre_exec function")
end

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

ACF mvc.lua example

2013-09-30T16:01:35Z

Ttrask: Test the code with acf-cli

ACF mvc.lua example

2013-09-30T15:15:42Z

Ttrask: Update the controller and model to current standards

ACF mvc.lua reference

2013-06-29T20:50:12Z

Ttrask: Remove links to deleted images and update to match current code

== mvc.lua function reference ==

This lua module provides the basics for creating an mvc application. It is patterned
loosely after the Ruby on Rails pattern - but much more simplistic.

The general pattern is to use the mvc '''new''' function to create a set of tables,
and then use '''new'' within those tables to create sub "objects". By using
metatable .__index methods, function references flow up through the parent tables.

=== new( self, modname ) ===

Returns 3 values: an ''mvc'' table and 2 booleans ( true or false if the ''modname''-controller and ''modname''-model.lua were loaded)

The ''mvc'' table contains:

{|
! table !! used for !! comments !! .__index points to
|-
|conf
|configuration items
|only created if a ''conf'' table does not exist in a parent
| n/a
|-
|clientdata
|data sent from the client
|only created if a ''clientdata'' table does not exist in a parent
| n/a
|-
|worker
|the "controller" methods
|if '''modname''' is given, then '''''modname'''-controller.lua'' module is loaded into this table. Otherwise, an empty table is returned.
|'''self''' (parent mvc object)
|-
|worker.mvc
|special methods run by the mvc dispatch function
|If the '''modname'''-controller.lua module does not initalize a .mvc table, an empty one is created
|'''self.mvc''' (parent mvc object's mvc table)
|-
|model
|the "model" methods
|if '''modname''' is given, then '''''modname'''-model.lua'' module is loaded into this table. Otherwise, an empty table is returned.
|'''worker''' (this mvc object's worker table)
|}

The returned table has a .__index method that points to '''worker''', so this table can
inherit values from the parent table.

If the '''''modname'''-controller.lua'' contains a .mvc.on_load function, the function is run before ''new'' returns.

The .__index metamethods mean that this code will set up inheritance as shown in the diagram:

require("mvc")
MVC=mvc:new()
APP=MVC:new()
controller=APP:new()
subcontroller=controller:new()

If you try to run '''subcontroller.model.somefunction()''', and it does not exist, the inheritance will look for somefunction() in ...

# subcontroller.worker
# controller
# controller.worker
# APP
# APP.worker
# MVC
# MVC.worker

This allows, for instance, the application to set a default method that is available to all child controllers. The reason the model looks to its parent worker table first is that controller methods are usually in the worker table, and models do not normally inherit from each other.

The calling code should be sure to call the ''destroy'' function when done with this object.

=== destroy ( self ) ===

Calls the ''mvc.on_unload'' function, if it exists, to close any resources opened by the object.

=== dispatch ( self, prefix, controller, action, clientdata ) ===

The gateway for executing controller actions in a protected xpcall.

# If no controller specified, use default prefix/controller
# Creates a '''self:new ( prefix .. controller)''' mvc object
# If no action specified, use controller default_action
# runs any existing ''worker.mvc.pre_exec'' function
# runs the ''worker.'''action'''''
# runs any existing ''worker.mvc.post_exec'' function
# gets the view function from ''view_resolver''
# executes the view with the results of the ''worker.'''action'''''
# and calls ''destroy'' to destroy the mvc object

If an error occurs, an exception_handler function is run. If possible, the exception handler of the new mvc object is run, otherwise ''self::exception_handler'' function handles the error. If an exception occurs after creating the new mvc object, ''mvc.on_unload'' is guaranteed to run, but ''mvc.post_exec'' is not.

=== soft_require ( self, modname ) ===

Looks for '''''modname'''.lua'' in ''self.conf.appdir'' and returns the results of a ''require()'' If the '''modname''' does not exist, returns nil.

This function allows modules to be loaded without generating an exception if they do not exist.

=== read_config ( self, modname ) ===

Looks in various places for a '''''modname'''.conf'' file and parses its contents into the '''self.conf''' table.

=== parse_path_info ( string ) ===

Returns 3 strings: a prefix, controller, and action. Given a string in the format of a URI or pathspec, returns the ''basename'' as the action, the last component of the ''dirname'' as the controller, and the
rest as the prefix. Missing components are returned as empty strings.

=== find_view ( appdir, prefix, controller, action, viewtype ) ===

Returns a string with the view filename for this combination of prefix/controller/action/viewtype or nil if no view file exists.

=== create_helper_library ( self ) ===

Returns a table of function pointers to be passed to each view.

=== auto_view (viewtable, viewlibrary, pageinfo, session) ===

This functions is used as the view of last resort. If no view file is found, this function is called to display the CFE resulting from the invoked action. The following 'viewtype's are supported:

* html
* json
* stream
* serialized

=== view_resolver ( self ) ===

Returns a function pointer to display the view, a table of functions made available to the view function, a table containing values of interest to the view, and a table containing the session data. The last three return values are designed to be the last three parameters to the view function pointer.

=== soft_traceback ( self, message ) ===

If called with no arguments, returns a ''debug.traceback'', otherwise returns "message".

=== exception_handler ( self, message ) ===

Prints an error message and then re-asserts the exception. Called if the xpcall in ''dispatch'' has an error.
This is the exception_handler of last resort. The application should provide
a more robust exception handler.

=== cfe ( table ) ===

Returns a table with ''value'', ''type'', and ''label'' values. If an input table is given in the call, those key/value pairs are added as well.
Guarantees the view will not get a "nil" on value, type, or label.
This function is added to the global (_G) environment so it is available to the entire application.

=== logevent ( message ) ===

Logs the message to syslog.

=== handle_clientdata ( form, clientdata ) ===

This is a helper function for controllers to implement forms. It parses the form CFE and applies any changes submitted by the user in clientdata.

=== handle_form ( self, getFunction, setFunction, clientdata, option, label, descr ) ===
This is a helper function for controllers to implement forms. It calls the getFunction to get the form CFE. If the form is submitted, it will call handle_clientdata and the setFunction to submit the form. The form CFE is returned.

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