ACF Libraries: Difference between revisions

From Alpine Linux
m (Reverted edits by RuthHughes (talk) to last revision by Dubiousjim)
 
(13 intermediate revisions by 6 users not shown)
Line 5: Line 5:
We are also using as a standard the lposix library which is documented here [[LPOSIX]]
We are also using as a standard the lposix library which is documented here [[LPOSIX]]


== Generic Libraries (acf-lib) ==


==[[date.lua]]==
===[[apk.lua]]===
Functions to load/unload apk packages
* delete - Deletes a package
* install - Installs a package
* version - Checks a package's installed version
 
===[[date.lua]]===
Date and time functions
Date and time functions
To be used with os.time() and os.date()
To be used with os.time() and os.date()
*date_to_seconds - Takes a date table and converts it to seconds from 1970
*date_to_seconds - Takes a date table and converts it to seconds from 1970
*seconds_to_date - Takes table of seconds values and converts to a date sorted smallest to largest
*seconds_to_date - Takes table of seconds values and converts to a date sorted smallest to largest
*string_to_table
*date_diff - Takes two values of seconds and gives back the difference
*date_diff - Takes two values of seconds and gives back the difference
*num_month_name - Month number to name of month
*num_month_name - Month number to name of month
*num_month_name_abr - Month number to abr of month
*num_month_name_abr - Month number to abr of month
*name_month_num -Month name to number
*name_month_num - Month name to number
*abr_month_num -Month abbreviation to number
*abr_month_num - Month abbreviation to number
*num_dow_name -Day of Week number to name
*num_dow_name - Day of Week number to name
*num_dow_abr - Day of week number to abbreviation
*num_dow_name_abr - Day of week number to abbreviation
*name_dow_num -Day of Week full name to number
*name_dow_num - Day of Week full name to number
*name_dow_num -Day of week abbreviation to number
*abr_dow_num - Day of week abbreviation to number
*what_tz - Checks to see what timezone the box is set to; /etc/TZ
*what_tz - Checks to see what timezone the box is set to; /etc/TZ
*change_tz - Changes the timezone
*change_tz - Changes the timezone
Line 27: Line 35:
***Months of the Year
***Months of the Year


== [[fs.lua]] ==
===[[format.lua]]===
Used to format tables and strings
*dostounix - Converts DOS line endings to Unix
*escapemagiccharacters - Escape Lua magic characters
*escapespecialcharacters - Escape shell special characters
*parse_lines - Takes out the blank and commented lines
*parse_linesandwords - Removes blanks and comments, and parses each line for words
*parse_configfile - Parses a config file for name/value pairs
*search_replace - Goes through a table of lines to search and replace
*search_for_lines - Goes through a file or table of lines and returns a table of matching lines
*cap_begin_word - Capitalizes beginning of words
*string_to_table - Takes a delimited string and turns it into a table
*expand_bash_syntax_vars - Takes a string and expands any ${...} constructs with the Lua variable
*replace_line - Removes the indicated line from a string and replaces it
*insert_line - Inserts a new line at the indicated location in a string
*get_line - Returns the specified line by number
*opts_to_table - Searches an option string for separate options and puts them in a table
*table_to_opts - Goes through an options table and creates the option string
*update_ini_file - Set a value in a particular ini section
*parse_ini_file - Read a value / values from an ini file
*get_ini_section - Read an entire section from an ini file
*set_ini_section - Set an entire section in an ini file
*get_ini_entry - Get an entry value from an ini file, accounting for parent sections and variables
 
=== [[fs.lua]] ===
Used for various filesystem specific functions
Used for various filesystem specific functions
*is_dir  - test if the a directory
*is_dir  - Test if the path is a directory
*is_file - test if is a file
*is_file - Test if the path is a file
*is_link - test if file is a link
*is_link - Test if the path is a link
*read_file / read_file_as_array - will read a file as a string / array
*create_directory - Creates a directory if it doesn't exist, including the parent dirs
*write_file - replace contents of a file
*remove_directory - Deletes a directory along with its contents
*write_line_file - appends lines to a file
*create_file - Creates a blank file (and the directory if necessary)
*find - Give a path and a filename and search for it
*copy_properties - Copies the permissions and ownership of one file to another
*copy_file - Copies a file to a directory or new filename (creating the directory if necessary)
*move_file - Moves a file to a directory or new filename (creating the directory if necessary)
*read_file / read_file_as_array - Reads a file as a string / array
*write_file - Replaces contents of a file
*write_line_file - Appends lines to a file
*find_files_as_array - Returns an array of files under "where" that match "what" (a Lua pattern)
*find - Give a path and a search string and iterate over matching files
*stat - Does almost the same as posix.stat, but instead it writes the output human readable


 
=== [[html.lua]] ===
== [[format.lua]] ==
Used to generate HTML code.
Used to format table,string,input,output ...
*cookie.set - Creates a cookie
*dostounix - converts dos line endings to unix
*cookie.unset - Clears a cookie
*remove_blanks_comments - takes out the blank and commented lines
*html_escape - Escapes HTML encoded strings
*table_to_string - formally the join.lua takes a table and makes into a string with delimiter
*entity - Outputs tags such as h1, h2, p, etc.
*string_to_table - formally split.lua. takes a delimited string and turns it into a table
*link - Creates a link tag
 
*Form setup functions - Create form tags
== [[html.lua]] ==
Functions used by web_elements.lua. Written by nangel for ACF.
*cookie.set -creates a cookie to be used with ACF
*html_escape - will escape html encoded strings
*nv_pair - returns name value pairings as string
*entity
*link
*cfe_unpack - returns the whole of a cfe as a string. Great for troubleshooting.
*Form setup functions - also are the "types" of cfe. See [[ACF_core_principles]]
**form.text
**form.text
**form.longtext
**form.longtext
**form.passwd
**form.password
**form.hidden
**form.hidden
**form.submit
**form.submit
Line 67: Line 98:
**form.stop
**form.stop


== menubuilder.lua ==
=== [[processinfo.lua]] ===
Written by nangel for ACF
Manages processes
 
*package_version - Returns the version of an apk package
== pidof.lua ==
*process_autostart - Returns a string describing run level of a process
=== pidof ===
*read_initrunlevels - Returns all processes in all run levels
find the process ID of a running program
*add_runlevels - Add a process to a list of run levels
*delete_runlevels - Remove a process from a list of run levels
*daemoncontrol - Start/Stop/Restart/... a process (calls /etc/init.d/service)
*pidof - Find the process ID of a running program


pidof.pidof(''program'')
=== [[validator.lua]] ===
This contains multiple different functions that each will validate input in there own way.
*is_string - Tests if a variable is of type string
*is_boolean - Tests if a variable is of type boolean
*is_number - Tests if a variable is of type number
*is_ipv4 - Tests if this is a valid ipv4 address
*is_partial_ipv4 - Tests if this is part of a valid ipv4 address
*is_mac - Tests to see if this is a valid mac address
*is_integer - Tests to see if a string contains an integer
*is_integer_in_range - Tests to see if a string contains an integer in a given range
*is_port - Tests to see if a string contains an integer in the IP port range
*is_valid_filename - Tests to see if a string is a valid filename and (optionally) located in a specified path


'''INPUT'''
== ACF-specific Libraries (acf-core) ==
* program
===[[authenticator.lua]]===
Authentication module.  This module loads one sub-authenticator module and exposes its functionality via '''auth''' table.
* authenticate
* get_userinfo
* get_userinfo_roles
* list_users
* change_settings
* new_settings
* delete_user


'''OUTPUT'''
===[[authenticator-plaintext.lua]]===
returns the PID's of running ''program'' or nil if there are none.
Authentication sub-module for plaintext database
* list_fields
* read_field
* delete_field
* write_entry
* read_entry
* delete_entry


'''CODING EXAMPLE'''
===[[controllerfunctions.lua]]===
require "pidof"
Controller helper functions
if pidof.pidof("mini_httpd") ~= nil then
* handle_clientdata
  print("mini_httpd is running")
* handle_form
else
* handle_startstop
  print("mini_httpd is not running")
end


== privsep.lua ==
=== menubuilder.lua ===
===drop_privs===
Written by nangel for ACF
Drop privileges while allowing a few functions still have root permissions.
*get_menuitems
privsep.drop_privs(user, group, functable)


Depends on ''posix'' and ''json''.
=== [[modelfunctions.lua]] ===
*getenabled
*startstop_service
*getstatus
*getfiledetails
*setfiledetails
*validateselect
*validatemulti
*write_file_with_audit


'''INPUT:'''<br>
=== [[roles.lua]] ===
* user
*list_controllers
* group
*get_controllers
* functable
*get_controllers_func
** a table of functions that will run as root
*get_controllers_view
 
*list_default_roles
'''OUTPUT:'''
*list_roles
returns a table identical to ''functable'', except the funcs are wrapped and runs in a separate process with root permissions.
*list_all_roles
 
*get_roles_perm
'''CODING EXAMPLE:'''
*get_role_perm
<pre>
*delete_role
#!/usr/bin/env lua
*set_role_perm
 
require "posix"
require "privsep"
 
-- register those as privileged funcs
a = {}
function a.getuid()
        return posix.getpid().euid
end
 
-- main ---------------------------------------------------------
priv = privsep.drop_privs("nobody", "nogroup", a)
if priv == nil then
        error("failed to drop privileges")
end
 
print("current uid:", posix.getpid().euid)
print("privileged uid:", priv.getuid())
</pre>
 
== [[session.lua]] ==
Written by nangel for ACF.
*random_hash - will create a bash64 like hash from /dev/urandom
*hash_ip_address -a hash encoded ip address
*ip_addr_from_hash -take the hash encoded ip and give me the ip
*serialize -go through a table or set of tables
*save_session -save the session table
 
 
== [[validator.lua]] ==
This contains multiple different functions that each will validate input in there own way.
*is_ipv4 - test if this is a valid ipv4 address
*is_mac - test to see if this is a valid mac address
*is_integer - is the number and int
*is_integer_in_range - is the int in the range of numbers
*is_port - the the number in the ip port range


== [[web_elements.lua]] ==
=== [[session.lua]] ===
Written by nangel for ACF.
Written by nangel for ACF.
*render_table -walks through a table rendered for a template
*random_hash - will create a bash64-like hash from /dev/urandom
*render_mainmenu - will render the side menu
*hash_ip_addr - create a hash encoded ip address
*render_submenu - will render all the sub menu items
*ip_addr_from_hash - take the hash encoded ip and give me the ip
*serialize - go through a table or set of tables and serialize
*save_session - save the session table
*load_session - load a saved session table
*unlink_session - delete a saved session table
*record_event - record an invalid login attempt
*count_events - check if there are too many invalid attempts
*expired_events - delete the expired invalid attempts and saved sessions


=== [[viewfunctions.lua]] ===
displayinfo - obsolete
displaymanagement - obsolete
*displayitem
*displayformitem
*displayform
*displaycommandresults


== split.lua <span style="color:red">put in format.lua</span>==
[[Category:ACF]] [[Category:Lua]]
== join.lua <span style="color:red">put in format.lua</span>==

Latest revision as of 12:30, 7 March 2016

ACF Libraries

Because of using lua, a very small language, the need arises to build everything from scratch. This can lead to some confusion, apprehension, or just feeling overwhelmed. Here is documentation on what we have now in the form of libraries and common functions. We hope to build some more and use this information to get the juices flowing in regard to ACF.

Some of these are lua libs or ones written for ACF. We are also using as a standard the lposix library which is documented here LPOSIX

Generic Libraries (acf-lib)

apk.lua

Functions to load/unload apk packages

  • delete - Deletes a package
  • install - Installs a package
  • version - Checks a package's installed version

date.lua

Date and time functions To be used with os.time() and os.date()

  • date_to_seconds - Takes a date table and converts it to seconds from 1970
  • seconds_to_date - Takes table of seconds values and converts to a date sorted smallest to largest
  • string_to_table
  • date_diff - Takes two values of seconds and gives back the difference
  • num_month_name - Month number to name of month
  • num_month_name_abr - Month number to abr of month
  • name_month_num - Month name to number
  • abr_month_num - Month abbreviation to number
  • num_dow_name - Day of Week number to name
  • num_dow_name_abr - Day of week number to abbreviation
  • name_dow_num - Day of Week full name to number
  • abr_dow_num - Day of week abbreviation to number
  • what_tz - Checks to see what timezone the box is set to; /etc/TZ
  • change_tz - Changes the timezone
    • Tables are included with this information
      • Timezones
      • Days of Week
      • Months of the Year

format.lua

Used to format tables and strings

  • dostounix - Converts DOS line endings to Unix
  • escapemagiccharacters - Escape Lua magic characters
  • escapespecialcharacters - Escape shell special characters
  • parse_lines - Takes out the blank and commented lines
  • parse_linesandwords - Removes blanks and comments, and parses each line for words
  • parse_configfile - Parses a config file for name/value pairs
  • search_replace - Goes through a table of lines to search and replace
  • search_for_lines - Goes through a file or table of lines and returns a table of matching lines
  • cap_begin_word - Capitalizes beginning of words
  • string_to_table - Takes a delimited string and turns it into a table
  • expand_bash_syntax_vars - Takes a string and expands any ${...} constructs with the Lua variable
  • replace_line - Removes the indicated line from a string and replaces it
  • insert_line - Inserts a new line at the indicated location in a string
  • get_line - Returns the specified line by number
  • opts_to_table - Searches an option string for separate options and puts them in a table
  • table_to_opts - Goes through an options table and creates the option string
  • update_ini_file - Set a value in a particular ini section
  • parse_ini_file - Read a value / values from an ini file
  • get_ini_section - Read an entire section from an ini file
  • set_ini_section - Set an entire section in an ini file
  • get_ini_entry - Get an entry value from an ini file, accounting for parent sections and variables

fs.lua

Used for various filesystem specific functions

  • is_dir - Test if the path is a directory
  • is_file - Test if the path is a file
  • is_link - Test if the path is a link
  • create_directory - Creates a directory if it doesn't exist, including the parent dirs
  • remove_directory - Deletes a directory along with its contents
  • create_file - Creates a blank file (and the directory if necessary)
  • copy_properties - Copies the permissions and ownership of one file to another
  • copy_file - Copies a file to a directory or new filename (creating the directory if necessary)
  • move_file - Moves a file to a directory or new filename (creating the directory if necessary)
  • read_file / read_file_as_array - Reads a file as a string / array
  • write_file - Replaces contents of a file
  • write_line_file - Appends lines to a file
  • find_files_as_array - Returns an array of files under "where" that match "what" (a Lua pattern)
  • find - Give a path and a search string and iterate over matching files
  • stat - Does almost the same as posix.stat, but instead it writes the output human readable

html.lua

Used to generate HTML code.

  • cookie.set - Creates a cookie
  • cookie.unset - Clears a cookie
  • html_escape - Escapes HTML encoded strings
  • entity - Outputs tags such as h1, h2, p, etc.
  • link - Creates a link tag
  • Form setup functions - Create form tags
    • form.text
    • form.longtext
    • form.password
    • form.hidden
    • form.submit
    • form.action
    • form.file
    • form.image
    • form.select
    • form.checkbox
    • form.start
    • form.stop

processinfo.lua

Manages processes

  • package_version - Returns the version of an apk package
  • process_autostart - Returns a string describing run level of a process
  • read_initrunlevels - Returns all processes in all run levels
  • add_runlevels - Add a process to a list of run levels
  • delete_runlevels - Remove a process from a list of run levels
  • daemoncontrol - Start/Stop/Restart/... a process (calls /etc/init.d/service)
  • pidof - Find the process ID of a running program

validator.lua

This contains multiple different functions that each will validate input in there own way.

  • is_string - Tests if a variable is of type string
  • is_boolean - Tests if a variable is of type boolean
  • is_number - Tests if a variable is of type number
  • is_ipv4 - Tests if this is a valid ipv4 address
  • is_partial_ipv4 - Tests if this is part of a valid ipv4 address
  • is_mac - Tests to see if this is a valid mac address
  • is_integer - Tests to see if a string contains an integer
  • is_integer_in_range - Tests to see if a string contains an integer in a given range
  • is_port - Tests to see if a string contains an integer in the IP port range
  • is_valid_filename - Tests to see if a string is a valid filename and (optionally) located in a specified path

ACF-specific Libraries (acf-core)

authenticator.lua

Authentication module. This module loads one sub-authenticator module and exposes its functionality via auth table.

  • authenticate
  • get_userinfo
  • get_userinfo_roles
  • list_users
  • change_settings
  • new_settings
  • delete_user

authenticator-plaintext.lua

Authentication sub-module for plaintext database

  • list_fields
  • read_field
  • delete_field
  • write_entry
  • read_entry
  • delete_entry

controllerfunctions.lua

Controller helper functions

  • handle_clientdata
  • handle_form
  • handle_startstop

menubuilder.lua

Written by nangel for ACF

  • get_menuitems

modelfunctions.lua

  • getenabled
  • startstop_service
  • getstatus
  • getfiledetails
  • setfiledetails
  • validateselect
  • validatemulti
  • write_file_with_audit

roles.lua

  • list_controllers
  • get_controllers
  • get_controllers_func
  • get_controllers_view
  • list_default_roles
  • list_roles
  • list_all_roles
  • get_roles_perm
  • get_role_perm
  • delete_role
  • set_role_perm

session.lua

Written by nangel for ACF.

  • random_hash - will create a bash64-like hash from /dev/urandom
  • hash_ip_addr - create a hash encoded ip address
  • ip_addr_from_hash - take the hash encoded ip and give me the ip
  • serialize - go through a table or set of tables and serialize
  • save_session - save the session table
  • load_session - load a saved session table
  • unlink_session - delete a saved session table
  • record_event - record an invalid login attempt
  • count_events - check if there are too many invalid attempts
  • expired_events - delete the expired invalid attempts and saved sessions

viewfunctions.lua

displayinfo - obsolete displaymanagement - obsolete

  • displayitem
  • displayformitem
  • displayform
  • displaycommandresults