Alpine Configuration Framework Design: Difference between revisions

From Alpine Linux
(This was really out of date. Tried to match current SVN.)
(cleaned up the page with headings and references and some rephrasing of sentence added wikitags)
 
(25 intermediate revisions by 13 users not shown)
Line 1: Line 1:
= Alpine Configuration Framework =
The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine Linux device. The primary focus is for a web interface - a light-weight MVC "webmin".


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


== Why Haserl + Lua ==
Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF: {{cmd|setup-acf}}


Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.
The above script install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages. To view ACF, simply browse to your machine https://<hostname>/


A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode.  After evaluating many options, we found that [http://www.lua.org Lua] has the following advantages:
Alternately, your existing web server can be used as follows:
* [[Install]] the packages {{pkg|acf-core}} and {{pkg|acf-alpine-baselayout}} and packages will install to {{path|/usr/share/acf}}.
* Configure your web server to give access to {{path|/usr/share/acf/www}} and run cgi scripts from {{path|/usr/share/acf/www/cgi-bin}} and you should be able to view ACF.


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


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


== Why ACF is MVC ==
Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.


The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:
A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that [https://www.lua.org Lua] has the following advantages:  


* '''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
*It is small (typically ~200KB of compiled code)
* '''View''' - code that formats data for output
*It compiles and runs much faster than [https://web.archive.org/web/20100707143932/http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl]{{dead link}} or [https://web.archive.org/web/20100313062645/http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
* '''Controller''' - code that glues the two together
*It provides a "normal" scripting language with [https://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, [[awk]], etc.


Note the lack of words like: HTML, XML, OO, AJAX, etc.  The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output. 
Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.
 
The flow of a single transaction is:
 
start ->
execute requested function in '''controller''',
optionally reading/writing a file using functions in the '''model''' ->
execute the '''view''' to format the output ->
end
 
''Every'' transaction follows this pattern.  For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model.  The presentation layer should be last on the priority list.
 
For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at
[http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf http://www.cs.usfcs.edu] or the [[Media:Mvc.templates.pdf|local copy]]  of the pdf.
 
= Starting ACF =
 
The easiest way to start ACF is to run the ''setup-webconf'' script.  This script will install mini-httpd, create a certificate, and start mini-httpd in HTTPS mode.  '''WARNING - This will give anyone on the network access to your machine.'''  The script will also install the two packages that are necessary for basic ACF: acf-core and acf-alpine-baselayout.  To view ACF, simply browse to your machine (https://<hostname>/).
 
Alternately, you can manually install ACF and your web server.  Once again, the two critical ACF packages are acf-core and acf-alpine-baselayout.  The ACF packages will install to /usr/share/acf.  You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.
 
If you would like to play with other ACF packages, we recommend you install the acf-apk-tools package.  This package will allow you to install / delete other packages using ACF.  You can then load any other acf-* packages you are interested in.
 
The two default login / password combinations are 'alpine' / 'test123' and 'foo' / 'test123'.  'alpine' is given ADMIN rights and 'foo' is given USER rights.  We recommend you change your login id and password by selecting 'User Management'.
 
= ACF Developer's Guides =
 
# [[ACF_mvc.lua_reference|mvc.lua reference]]  - mvc.lua is the core of ACF
# [[ACF_mvc.lua_example|mvc.lua example]] - build a simple (command-line) application
# [[ACF_acf_www-controller.lua_reference|acf www-controller reference]] - ACF www application functions
# [[ACF_acf_www_example| acf www-controller example]] - webify the above examples
# [[ACF_how_to_write]] - Step by step howto for writing acfs
# [[ACF core principles]] - Things that are standard across the application
# [[LPOSIX]] - Documentation for the Lua Posix functions
# [[ACF Libraries ]] - Document the libraries and common functions
# [[Writing ACF Views]] - Guide for writing a view
# [[Writing ACF Controllers]] - Guide for writing a controller
# [[Writing ACF Models]] - Guide for writing a model
 
= ACF Layout =
ACF has support for multiple skins.<BR>
Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.
== Howto contribute ==
First download ACF using svn or installing available acf's using apk_add.<BR>
Easiest is if you download latest Alpine ISO, boot a box on that and then run 'setup-alpine' and 'setup-webconf -a' that way you get a running environment fast and easy!<BR>
Some example skins are available
* /usr/share/acf/www/skins/ice/
* /usr/share/acf/www/skins/snow/
Make a new skin-folder
mkdir /usr/share/acf/www/skins/myskin
Create a css file called as the folder.
touch /usr/share/acf/www/skins/myskin/myskin.css
Now you can start editing your myskin.css.<BR>
If you have ACF running on a computer, you can browse to this ACF-page and switch to your knew skin (called myskin) and see the results of your changes.
 
Pack your myskin-folder, containing your css-file (and images, if there is any).<BR>
Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [http://wiki.alpinelinux.org/w/index.php?title=Mailing_lists subscribe] before sending your patch)''
 
= ACF Modules =
 
== Networking ==
Networking related modules.
 
=== DHCP server ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''isc-dhcp'''.
|}
* Edit global settings
* Create/Edit/Delete subnets and hosts
* View leases
 
=== DNS ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''tinydns'''.
|}
* View current DNS configuration/information
* Create/Edit/Delete domain files
* Per user and per role permissions
 
=== DNScache ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''dnscache'''.
|}
* Edit configuration
* Edit allowed clients
* Create/Edit/Delete DNS server entries
 
=== DNSmasq ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''dnsmasq'''.
|}
* Edit configuration
* View leases
* View logfile
 
=== Chrony ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''chrony'''.
|}
* Edit configuration
* View logfile
 
=== NTPD ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure timeserver '''openntpd'''.
|}
* Edit configuration
* View logfile
 
=== SSH ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''openssh'''.
|}
* View connections
* Edit configuration
* Edit authorized keys
 
=== Fetchmail ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''fetchmail'''.
|}
* Edit global settings
* Create/Edit/Delete mailbox/domain entries
 
=== Samba ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''samba'''.
|}
* Edit configuration
* Create/Edit/Delete shares
* Join domain
 
=== TCPproxy ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''tcpproxy'''.
|}
* Edit configuration
* Create/Edit/Delete STMP Proxy entries and files
 
=== Firewall ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''shorewall'''.
|}
* Edit configuration
* View logfile
 
=== OpenVPN ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''openvpn'''.
|}
* Create/Edit/Delete configs
* View logfile
 
=== IPsec ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''ipsec-tools'''.
|}
* Edit configuration
* Upload/View/Delete certificates
* View logfile
 
=== IPtables ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''iptables'''.
|}
* Edit configuration (rules-save file)
* Create/Edit/Delete chains and rules
 
=== NHRP ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''opennhrp'''.
|}
* Edit configuration
 
=== Zebra and BGP ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''quagga'''.
|}
* View routes
* Edit configuration
 
 
== Applications ==
Application related modules
 
=== Certificate Authority ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Generate / sign certifiates using '''openssl'''.
|}
* Edit configuration
* View/Create/Upload CA certificate
* Edit certificate defaults
* Generate/View/Delete/Approve requests
* View/Download/Renew/Revoke certificates
* Generate and download CRLs
 
=== Web Proxy ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''squid'''.
|}
* Edit configuration
* Edit user list
* Edit associated files
 
=== Content Filter ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''dansguardian'''.
|}
* Edit configuration
 
=== Snort ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''snort'''.
|}
* View alerts
* Edit configuration
 
=== Gnats ===
{|
| '''Status:''' || ''Work in progress''
|-
| '''Summary:''' || Configure '''gnats'''.
|}
* Edit configuration
* Report a bug
* Query problem reports
 
 
== System ==
System/Other related modules
 
=== Interfaces ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Local interface management
|}
* Create/Edit/Delete interfaces
* Bring up/down interfaces and restart networking
 
=== General health ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Show status on your running system.
|}
* Show system status
* Show storage status
* Show network status
* Graph network activity
* Show modules status
* Show proc status


=== User Management ===
== Why ACF is MVC  ==
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || ACF User management
|}
* Edit self
* Create/Edit/Delete ACF users
* View roles for user


=== Roles Management ===
The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:  
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || ACF Roles management
|}
* View own permissions
* Create/Edit/Delete ACF roles
* View all possible permissions


=== Packages ===
*'''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
{|
*'''View''' - code that formats data for output
| '''Status:''' || Ready for betatest
*'''Controller''' - code that glues the two together
|-
| '''Summary:''' || Manage system packages ('''apk-tools''')
|}
* View/Delete loaded packages
* View/Install available packages
* Edit configuration


=== Modules ===
Note the lack of words like: HTML, XML, OO, AJAX, etc. The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Manage system modules
|}
* View loaded modules
* Edit/Reload modules file


=== Startup ===
The flow of a single transaction is:  
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Manage system startup
|}
* View/Edit service startup sequence


=== Cron ===
start -&gt; execute requested function in '''controller''', optionally reading/writing a file using functions in the '''model''' -&gt; execute the '''view''' to format the output -&gt; end
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Manage periodic jobs ('''cron''')
|}
* Edit configuration
* Create/Edit/Delete periodic jobs


=== System logging ===
''Every'' transaction follows this pattern. For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model. The presentation layer should be last on the priority list.  
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''syslog'''.
|}
* Edit configuration


=== Logfiles ===
Of course, as with all MVC designs, the ACF MVC design is not quite 'pure' MVC and has evolved over time. Most of the '''controller''' functionality is handled by the framework code. The framework code will also automatically generate views for HTML, JSON, and a few other viewtypes if no '''view''' is defined. Also, many '''model''' functions are implemented in helper libraries. We have attempted to make it as easy as possible to develop new ACF modules.
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Manage logfiles.
|}
* View/Tail/Download/Delete logfiles


=== Skins ===
For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at [https://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf https://www.cs.usfcs.edu].
{|
| '''Status:''' || Ready for use
|-
| '''Summary:''' || Switch ACF skin
|}
* Select ACF skin


=== Local Backups ===
== ACF Developer's Guides  ==
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Saves your settings to floppy/usb/other media ('''lbu''').
|}
* Show unsaved changes
* Edit configuration
* Commit/Save changes to media
* Select backup archives
* Generate and download overlay


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


== DevTools ==
== How to contribute  ==
DevTools is a (set of) ACF(s) that could come in handy when developing ACF.


=== SVN status ===
ACF has support for multiple skins. Some example skins available are:  
{|
*/usr/share/acf/www/skins/alps/  
| '''Status:''' || Ready for use
*/usr/share/acf/www/skins/cloud/
|-
*/usr/share/acf/www/skins/ice/
| '''Summary:''' || Different information/functions related to the SVN-tree
*/usr/share/acf/www/skins/snow/
|}
*/usr/share/acf/www/skins/wik/
* svn status (Shows whats changed since last 'svn update')
* svn diff (Shows difference on your computer and on svn-server)
* svn log (Shows the changelog 1 week back in time)
* svn update (Fetch all available updates)


Feel free to contribute in programming css-stylesheets for ACF.


== ToDo ==
* Make a new skin folder.{{Cmd|# mkdir -p /etc/acf/skins/myskin}}
* Create a css file called as the folder. {{Cmd|# touch /etc/acf/skins/myskin/myskin.css}}


=== VPN ===
Now you can start editing your myskin.css.<br>If you have ACF running on the computer, you can browse to https://&lt;hostname&gt;/cgi-bin/acf/acf-util/skins/read and switch to your new skin (called myskin) and see the results of your changes.  
Needs to be split into an administrative end for letting people connect to you (rogue warriors,personal laptop size connectivity) and VPN connectivity to other sites (remote office or location). These two are configured differently.


Still not started modules.
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 [[Alpine_Linux:Mailing_lists|subscribe]] before sending your patch)''


=== Dialup ===
== See also ==
Start/Stop Dialup connection


=== Dialup/PPPoE ===
* [https://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
Configure Dialup/PPP/PPPoE connectivity. Maybe other Internet connections that aren't ethernet (handled in Interfaces).
* [https://www.lua.org/pil/ Programming in Lua (first edition)]


=== Diagnostic ===
[[Category:ACF]] [[Category:Lua]]
Stats/Resource use/maybe graphs-rrd.  Ability to run ''ping'' command.

Latest revision as of 05:32, 10 March 2025

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

Installation

Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF:

setup-acf

The above script install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages. To view ACF, simply browse to your machine https://<hostname>/

Alternately, your existing web server can be used as follows:

  • Install the packages acf-core and acf-alpine-baselayout and packages will install to /usr/share/acf.
  • Configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin and you should be able to view ACF.

ACF packages page details the available ACF modules and their status. Proceed to Managing ACF page for Managing Your ACF Installation.

Why Haserl + Lua

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

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

  • It is small (typically ~200KB of compiled code)
  • It compiles and runs much faster than PHP, Perl[Dead Link] or Ruby
  • It provides a "normal" scripting language with features similar to PHP, perl, java, awk, etc.

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

Why ACF is MVC

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

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

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

The flow of a single transaction is:

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

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

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

For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at https://www.cs.usfcs.edu.

ACF Developer's Guides

  1. mvc.lua reference - mvc.lua is the core of ACF
  2. mvc.lua example - build a simple (command-line) application
  3. acf www-controller reference - ACF www application functions
  4. acf www-controller example - webify the above examples
  5. ACF how to write - Step by step howto for writing ACF modules
  6. ACF core principles - Things that are standard across the application
  7. LPOSIX - Documentation for the Lua Posix functions
  8. ACF Libraries - Document the libraries and common functions
  9. Writing ACF Views - Guide for writing a view
  10. Writing ACF Controllers - Guide for writing a controller
  11. Writing ACF Models - Guide for writing a model

How to contribute

ACF has support for multiple skins. Some example skins available are:

  • /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/

Feel free to contribute in programming css-stylesheets for ACF.

  • Make a new skin folder.

    # mkdir -p /etc/acf/skins/myskin

  • Create a css file called as the folder.

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

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

Pack your myskin folder, containing your css file (and images, if there are any).
Send this patch to acf@lists.alpinelinux.org (Note: Don't forget to subscribe before sending your patch)

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Alpine_Configuration_Framework_Design&oldid=29214"