nix-amer/README.md

| nix-amer |

name:        nix-amer
version:     0.1.0
description: Configuration automation tool
author:      xdrm-brackets

Need to automate the setup of your linux server or desktop ? This tool is made for you.

• I. How to use
  • 1) Requirements
  • 2) Installation
  • 3) Usage
    • 1. Create build file
    • 2. Run on the target
• II. Commands
  • 1) Comments
  • 2) Install/remove Packages
  • 3) Setup configuration
  • 4) Service management
  • 5) Custom scripts
  • 6) Copy files
  • 7) Aliases
• III. Path Expressions
  • 1) Syntax
  • 2) File Formats

• Example

---

I. How to use

1) Requirements

In order to install the nix-amer executable, you must have :

• any recent linux system (has not been tested over other OS)
• go installed (has not been tested under version 1.11)

2) Installation

Simply launch the following command in any terminal

$ go get -u github.com/xdrm-brackets/nix-amer

For those who don't know, it will load the project sources into $GOPATH/src/github.com/xdrm-brackets/nix-amer and compile into the executable at $GOPATH/bin/nix-amer.

3) Usage

1. Create build file

The first step is to write your build file according to the installation you want. While writing your build file you can check the syntax by using the -dry-run command-line argument as follows :

$ nix-amer -p apt-get -dry-run <path/to/build/file>

The -p argument (package manager) is mandatory but it will have no effect in -dry-run mode. You can use for instance apt-get as a default.

2. Run on the target

Once your build file is correct and fulfills your needs, you can log in to the target machine, install the nix-amer and run it with your build file. Nix-amer's rich and colorful command-line output will give you a good feedback to rapidly fix problems.

---

II. Commands

Your whole setup remains in 1 only build file. Each line contains one instruction, the list of instructions is listed below.

1) Comments

Each line beginning with one of the following characters : [, # or ; is considered a comment and is not interpreted.

2) Install/remove Packages

These instructions allow you to interact with the package system available on your system.

install <packages>

Install the listed packages. If more than one, use spaces to separate package names.

delete <packages>

Remove the listed packages. If more than one, use spaces to separate package names.

3) Setup configuration

This instruction allow you to set fields of configuration files without the need of an editor and in a developer-readable manner.

set <expr> <content>

Update a configuration file where <expr> is a dot-separated human-readable path expression and <content> is a string or a file. If a string is given, it will override/add the field ; if a file is given the configuration file will be replaced by it.

4) Service management

These instructions allow you to interact with the service system (cf. systemd).

service [enable|start|stop|restart|reload] <services>

Perform the action on services. If more than one, use spaces to separate service names.

5) Custom scripts

This instruction allows you to use custom scripts for complex operations.

run <script>

Execute the executable located at the path <script>. If script is an alias it will resolve to its path

6) Copy files

This instruction allows you to copy files.

copy <src> <dst>

Try to copy the file <src> to the path <dst>.

7) Aliases

The file format allows you to create aliases to file paths for more readability in the path expression or with the run command.

alias name /path/to.file

Create the alias name which resolves to the path /path/to.file.

Alias value either for the set or run command have priority to real file paths.

---

III. Path Expressions

1) Syntax

The syntax is pretty fast-forward, it uses 2 levels (file, fields) to find your configuration line : location_or_alias@fields.

Field	Description	Example
location_or_alias	Path to the configuration file to edit. The file will be created if not found. If the path is an alias created before in the file, it will resolve to the alias value as a filename.	/etc/nginx/nginx.conf, some-alias
fields	Dot-separated chain of strings that match a configuration field. If the field does not point to a raw field but an existing field container, the <value> will replace the group with a text value.	AllowGroups, http.gzip

The fields is processed only for known file formats listed in this section.

2) File Formats

Configuration files can be written according to some standards or application-specific syntax. This tool uses standard and third-party to parse the following formats :

• xml and json are read/written using the go standard library (cf. json, xml).

xml is not yet supported ; complex structure the library outputs (attributes vs. content) to understand better

• yaml with go-yaml/yaml.

• ini with go-ini/ini.

• nginx configurations with my own library.

• and more to come...

---

Example

Launch the following command to install your server :

$ nix-amer -p apt-get myserver.build

Replace apt-get by your package manager; nix-amer -help for available options.

myserver.build

# [pre] is executed before launching everything else
[pre]
install nginx ssh sslh
alias nginx /etc/nginx/nginx.conf
alias sshd  /etc/ssh/sshd_config
alias sslh  /etc/default/sslh

[nginx]
set nginx@http.gzip           off
service enable nginx
service start nginx

[sshd]
set sshd@PermitRootLogin      no
set sshd@PermitEmptyPasswords no
service enable sshd
service enable ssh

[sslh]
set sslh@RUN                  yes
set sslh@DEAMON_OPTS          "--user sslh --listen 0.0.0.0:443 --ssh 127.0.0.1:22 --ssl 127.0.0.1:44300 --pidfile /var/run/sslh/sslh.pid"
service enable sslh
service start sslh