5,705
edits
Changes
Platform Team/Server Kit/Mace (view source)
Revision as of 05:48, 21 March 2012
, 05:48, 21 March 2012moved Sugar Server Kit/Mace to Platform Team/Server Kit/Mace: Move SSK to HSD
The mace is a tool to ma<strike>c</strike>ke final configuration using source templates. Mace is supposed to help with configuration of services on Server based school servers.
The mace is a tool to ma<strike>c</strike>ke final configuration using source templates. Mace is supposed to help with configuration of services on Server based school servers.
These are the core differences compared with tools like Puppet or Cfengine:
These are the core differences compared with tools like Puppet or Cfengine that makes mace a different niche project:
* mace doesn't provide new metaphors, people need to follow the same configuration syntax for particular services;
* mace provides a simple and straightforward usage workflow, i.e., with tools like Puppet, users need to ''"code"'' a configuration (starting from regular coding in Ruby for missing functions or types, and ending with handling the relationships between all configured resources). It is different in mace; users only need to enter a configuration for the particular service, the rest (like dependencies between configured services) is already coded in mace;
* mace is not intended to be a unified system like Puppet or Cfenginei, it supports only a limited set of services (what Server based solution provides), but does it well, e.g., for iptables, just write rules, and the rest will be done by mace;
* mace doesn't provide new metaphors; people need to follow the standard configuration syntax for any particular service;
* mace doesn't function like a daemon, it just converts configuration sources to the final configuration on the final server, e.g., as a post procedure after installing packages;
* mace is not intended to be a unified system like Puppet or Cfengine; it supports only a limited set of services (of those that the Server based solution provides), but does it well, e.g., for iptables, just write rules, and the rest will be done by mace;
* mace is designed to support intermediate customizing, i.e., the original configuration, provided by an upstream project, might be supplemented (not patched) in the downstream product before deploying to the final users.
* mace doesn't function like a daemon; it just converts configuration sources to the final configuration on the final server, e.g., as a post procedure after installing packages;
* mace is designed to ease support of intermediate customizing, i.e., the original configuration, provided by an upstream project, might be supplemented (not patched) in the downstream product before deploying it to the final users.
* within the [[Sugar Server Kit]] initiative, mace is intended to support, mostly, only the [[Sugar_Server_Kit/Architecture#Dumb_school_servers|Dumb school servers]] functional model.
== Configuration sources ==
== Configuration sources ==
Sources for {{Code|mace}} are stored in GNU/Linux distribution agnostic manner in form of:
Sources for {{Code|mace}} are stored in a GNU/Linux distribution agnostic manner, in this form:
[<arbitrary-path>]/<service-name>.d/[<service-confile>]/<configuration-file>.conf
[<arbitrary-path>]/<service-name>.d/[<service-confile>]/<configuration-file>.conf
In addition to configuration files, Mace can process files with a {{Code|.env}} suffix. These files contain variable declarations in Bash syntax. The values of these variables might be entered in configuration files in the form of {{Code|@VARIABLE@}}, in which case they will be expanded to real values while applying the configuration.
In addition to configuration files, Mace can process files with a {{Code|.env}} suffix. These files contain variable declarations in Bash syntax. The values of these variables might be entered in configuration files in the form of {{Code|@VARIABLE@}}, in which case they will be expanded to real values while applying the configuration.
In addition to custom variables, there is a list of special ones:
* variables exported by providers;
* {{Code|''<provider>''_SERVICE}} variables with paths to {{Code|/etc/init.d}} services for all providers that support services;
* {{Code|SRC_ROOT}}, path to the root directory with configuration sources;
* {{Code|DST_ROOT}}, path to the root directory to place final configuration;
* {{Code|INCLUDE}}, if this variable is set in {{Code|.env}} files, it will be treated as a colon separated list of directories to search for additional configuration sources; if {{Code|INCLUDE}} directories are not absolute, they will be referenced from the [[Sugar_Server_Kit/sugar-server-templates|sugar-server-templates]] root;
* {{Code|PWD}}, path to the directory where current source configuration file is located.
=== Keywords ===
Source configuration file names might contain substrings in format
[''keyword'']
which will tell Mace that this source file can be processed only if this particular keyword is enabled in Mace by mentioning the keyword name in the {{Code|--keywords}} command-line argument.
By default, Mace has these keywords enabled:
* ''production''
For example, if there is a sources tree,
<dir> +squid.d
<config> | +010.base.conf
<config> | +020.log[production].conf
<config> | +020.log[test].conf
the final configuration tree will be as follows:
<dir> +squid.d
<config> | +010.base.conf
<config> | +020.log[production].conf
== Configuration application ==
== Configuration application ==
To start the applying process:
To start the applying process:
sudo mace apply -v
sudo mace apply
If the sources path is not the default, {{Code|/etc/mace}}, use the {{Code|--input}} argument to specify the right one.
== Providers ==
Providers is the way how Mace can configure particular services. Providers don't contain high-level configuration logic, configuration will happen only basing on configuration sources passed to the Mace to process by these providers. At the same time, providers might do some extra work, e.g.,
to make sure that service's directory are created. See providers [http://api.sugarlabs.org/mace/pages/providers.html documentation] for more information how particular provider might affect final system after configuration application.
Mace supports only a limited number of [http://api.sugarlabs.org/mace/pages/providers.html#supported-systems GNU/Linux distributions] and [http://api.sugarlabs.org/mace/pages/providers.html#list-of-providers services]. That's because Mace is supposed to be used mostly as a school server configuration tool.
== Templates ==
== Templates ==
The project [[The_Server/sugar-server-templates|sugar-server-templates]] is intended to provide most of basic configurations that might be useful for schools servers. After installing it from packages, the final configuration might be composed by symlinking templates from {{Code|/usr/share/sugar-server}} directory to the directory where Mace will find it, by default in {{Code|/etc/sugar-server}}.
The project [[Sugar Server Kit/sugar-server-templates|sugar-server-templates]] is intended to provide most of basic configurations that might be useful for schools servers. After installing it from packages, the final configuration might be composed by symlinking templates from {{Code|/usr/share/sugar-server-templates}} directory to the directory where Mace will find it, by default in {{Code|/etc/mace}}.
== Configuration ==
By default, configuration occurs based on several sources (sorted by applied order):
* {{Code|/etc/mace.conf}} system-wide configuration file,
* {{Code|~/.local/mace/config}} user-wide configuration file,
* {{Code|mace}}'s command-line arguments.
Configuration files contain option names equal to command-line arguments. To get the current configuration, call:
mace config
== Troubleshooting ==
* By default, if mace can't start configuring services with new configuration, it falls back to the old configuration. It might be not very useful in case of investigating new configuration errors. To prevent such behavior use {{Code|-R}} command-line argument and try to start affected service manually (with new configuration):
mace apply -R
/etc/init.d/<SERVICE> start
== Testing routines ==
== Testing routines ==
== Getting involved ==
== Getting involved ==
* Read [http://api.sugarlabs.org/mace/pages/HACKING.html HACKING] file,
* [http://bugs.sugarlabs.org/newticket?component=sugar-server-kit Report bugs].
* Read [http://api.sugarlabs.org/mace documentation] auto generated from sources.
* Read the [http://api.sugarlabs.org/mace/pages/HACKING.html HACKING] file to know how to contribute with code.
== Resources ==
* [http://git.sugarlabs.org/server/mace Sources].
* [http://api.sugarlabs.org/mace Documentation] auto generated from sources.