Alpine Configuration Framework Design: Difference between revisions

From Alpine Linux
m (→‎Starting ACF: Removed obsolete warning.)
 
(29 intermediate revisions by 13 users not shown)
Line 1: Line 1:
= Alpine Configuration Framework =
= Alpine Configuration Framework =


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


== Why Haserl + Lua ==  
== Why Haserl + Lua ==


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


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


* It is small (typically ~200KB of compiled code)
*It is small (typically ~200KB of compiled code)  
* It compiles and runs much faster than [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl] or [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
*It 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]  
* It provides a "normal" scripting language with [http://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, awk, etc.  
*It provides a "normal" scripting language with [https://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.
Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.


== Why ACF is MVC ==
== Why ACF is MVC ==


The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:
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.
*'''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
*'''View''' - code that formats data for output  
* '''Controller''' - code that glues the two together
*'''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.  
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:
The flow of a single transaction is:  


start ->
start -> execute requested function in '''controller''', optionally reading/writing a file using functions in the '''model''' -> execute the '''view''' to format the output -> end  
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.
''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
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.
[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.


= ACF Developer's Guides =
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].


# [[ACF_mvc.lua_reference|mvc.lua reference]] - mvc.lua is the core of ACF
= Starting ACF =
# [[ACF_mvc.lua_example|mvc.lua example]] - build a simple (command-line) application
Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF:
# [[ACF_acf_www-controller.lua_reference|acf www-controller reference]] - ACF www application functions
{{cmd|setup-acf}}
# [[ACF_acf_www_example| acf www-controller example]] - webify the above examples
''(This script will install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages.)''<BR>
# [[ACF_how_to_write]] - Step by step howto for writing acfs


# [[ACF core principles]] (Things that are standard across the application)
To view ACF, simply browse to your machine https://&lt;hostname&gt;/
# [[LPOSIX]] Documentation for the Lua Posix functions
# [[ACF Libraries ]] Document the libraries and common functions


= ACF Layout =
See also [[Managing ACF|Managing Your ACF Installation]]
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 funning envionment fast and easy!<BR>
Some example skins are available
* $PATH/www/ice/
* $PATH/www/snow/
Make a new skin-folder
mkdir $PATH/www/myskin
Create a css file called as the folder.
touch $PATH/www/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 chagens.


Pack your myskin-folder, containing your css-file (and images, if there is any).<BR>
{{tip|Alternately, you can manually install ACF and your web server. The two critical ACF packages are acf-core and acf-alpine-baselayout. The ACF packages will install to /usr/share/acf. You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.}}
Send this patch to acf@lists.alpinelinux.org


= ACF Modules =
= ACF Developer's Guides  =


== Networking ==
#[[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
Networking related modules.
#[[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


=== DHCP server ===
== Other useful links  ==
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''isc-dhcp'''.
|}
* Edit global settings
* Edit subnets
* Generate config-files


=== Firewall ===
#[https://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
{|
#[https://www.lua.org/pil/ Programming in Lua (first edition)]
| '''Status:''' || Ready for betatest
#[[Managing ACF]]
|-
| '''Summary:''' || Configure '''shorewall'''.
|}
* Show program status
* Guided configuration
* Expert configuration
* Show logfile


=== NTPD ===
= ACF Layout  =
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure timeserver '''openntpd'''.
|}
* Show program status
* Guided configuration
* Expert configuration
* Show logfile


=== OpenVPN ===
ACF has support for multiple skins.<br>Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.
{|
| '''Status:''' || Ready for alphatest
|-
| '''Summary:''' || Configure timeserver '''openntpd'''.
|}
* Show available configs
* Show config-details
* Guided configuration '''ToDo'''
* Edit config in expert mode
* Show certificate information '''ToDo'''
* Show logfile


=== DNS ===
== How to contribute  ==
{|
| '''Status:''' || [[Work in progress]]
|-
| '''Summary:''' || Configure '''tinydns'''.
|-
| '''ToDo:''' || Caching/Hosting/for both Internet and Inside firewall nets
|}
* View current DNS-configuration/information
* Edit config-files


=== Fetchmail ===
First, download ACF using git or installing available ACF modules using 'apk add'.<br>Easiest is if you download the latest Alpine Linux ISO, boot a box from the ISO and then run 'setup-alpine' and 'setup-acf'. That way you get a running environment fast and easy!<br>Some example skins are available:  
{|
| '''Status:''' || [[Work in progress]]
|-
| '''Summary:''' || '''fetchmail''' configuration/Relay host/store and forward.
|}
* Show program status
* Guided configuration
* Expert configuration


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


== Applications ==
Make a new skin folder.
Application related modules


=== Web Proxy ===
mkdir -p /etc/acf/skins/myskin
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''squid'''.
|}
* Show program status
* Guided configuration


=== Content Filter ===
Create a css file called as the folder.  
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''dansguardian'''.
|}
* Show program status
* Guided configuration


=== Snort ===
touch /etc/acf/skins/myskin/myskin.css
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''snort'''.
|-
| '''ToDo:''' || Figure out what acf-snort needs to do more.
|}
* Show program status
* Show alert-list
* Expert configuration


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.


== System ==
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)''
System/Other related modules


=== Interfaces ===
= ACF Packages  =
{|
| '''Status:''' || [[Work in progress]]
|-
| '''Summary:''' || Local interface management
|}
* Show configured interfaces
* Edit/delete interfaces
* Add new interfaces


=== LBU ===
Look at [[ACF packages]] to see available ACF modules and their status.
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Saves your settings to floppy/usb/other media.
|}
* Show program status
* Show unsaved changes
* Guided configuration
* Expert configuration
* Commit/Save changes to media


=== General healt ===
[[Category:ACF]] [[Category:Lua]]
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Show status on your running system.
|}
* Show system status
* Show storage status
* Show network status
* Show modules status
* Show proc status
 
=== System logging ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || Configure '''syslog'''.
|}
* Show program status
* Guided configuration
* Expert configuration
 
=== Logfiles ===
{|
| '''Status:''' || Ready for betatest
|-
| '''Summary:''' || View/Delete/Download logfiles.
|}
* Delete logfiles
* View logfiles
* Download logfiles
 
=== Skins ===
{|
| '''Status:''' || Ready for use
|-
| '''Summary:''' || Switch skin.
|}
* Switch skin
 
 
== DevTools ==
DevTools is a (set of) ACF(s) that could come in handy when developing ACF.
 
=== SVN status ===
{|
| '''Status:''' || Ready for use
|-
| '''Summary:''' || Different information/functions related to the SVN-tree
|}
* svn info (Shows overview of the svn-tree on the svn-server)
* svn update (Fetch all available updates)
* svn diff (Shows difference on your computer and on svn-server)
* svn status (Shows whats changed since last 'svn update')
* svn log (Shows the changelog 1week back in time)
 
 
== ToDo ==
Still not started modules.
 
=== Routing ===
This is for remote/multi box routing, bgp...etc
 
=== VPN ===
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 are to configured differently.
 
=== Dialup ===
Start/Stop Dialup connection
 
=== Dialup/PPPoE ===
Configure Dialup/PPP/PPPoE connectivity. Maybe other Internet connections that aren't ethernet-which is Interfaces
 
=== Source Manager ===
Way to change the /etc/apk/apk.conf
 
=== Package Manager ===
Way to say what to upgrade-install-remove...apk_*
 
=== Password Manager ===
Local password changer
 
=== Diagnostic ===
Stats/Resource use/maybe graphs-rrd

Latest revision as of 01:59, 4 September 2023

Alpine Configuration Framework

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

Why Haserl + Lua

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

A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that 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.

Starting ACF

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

setup-acf

(This script will install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages.)

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

See also Managing Your ACF Installation

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

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

Other useful links

  1. Lua 5.1 Reference Manual
  2. Programming in Lua (first edition)
  3. Managing ACF

ACF Layout

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

How to contribute

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

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

Make a new skin folder. 

mkdir -p /etc/acf/skins/myskin

Create a css file called as the folder. 

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

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

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

ACF Packages

Look at ACF packages to see available ACF modules and their status.

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