nix-amer/README.md

# | nix-amer |

[![Go version](https://img.shields.io/badge/go_version-1.11-blue.svg)](https://golang.org/doc/go1.11)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Report Card](https://goreportcard.com/badge/github.com/xdrm-brackets/nix-amer)](https://goreportcard.com/report/github.com/xdrm-brackets/nix-amer)
[![Coverage Status](https://coveralls.io/repos/github/xdrm-brackets/nix-amer/badge.svg?branch=master)](https://coveralls.io/github/xdrm-brackets/nix-amer?branch=master)
[![CircleCI Build Status](https://circleci.com/gh/xdrm-brackets/nix-amer.svg?style=shield)](https://circleci.com/gh/xdrm-brackets/nix-amer)
[![Go doc](https://godoc.org/github.com/xdrm-brackets/nix-amer?status.svg)](https://godoc.org/github.com/xdrm-brackets/nix-amer)

```yaml
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.

<!-- toc -->

  * [I. How to use](#i-how-to-use)
    + [1) Requirements](#1-requirements)
    + [2) Installation](#2-installation)
    + [3) Usage](#3-usage)
        * [1. Create build file](#1-create-build-file)
        * [2. Run on the target](#2-run-on-the-target)
  * [II. Commands](#ii-commands)
    + [1) Comments](#1-comments)
    + [2) Install/remove Packages](#2-installremove-packages)
    + [3) Setup configuration](#3-setup-configuration)
    + [4) Service management](#4-service-management)
    + [5) Custom scripts](#5-custom-scripts)
    + [6) Copy files](#6-copy-files)
    + [7) Aliases](#7-aliases)
  * [III. Path Expressions](#iii-path-expressions)
    + [1) Syntax](#1-syntax)
    + [2) File Formats](#2-file-formats)
- [Example](#example)

<!-- tocstop -->

----

### 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

```bash
$ 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 :

```bash
$ 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](#ii-path-expressions) and \<content\> is a string or a file. If a string is given, it will <u>override/add the field</u> ; if a file is given the configuration file will be <u>replaced</u> by it.




#### 4) Service management

These instructions allow you to interact with the service system (_cf. [systemd](https://github.com/systemd/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](#7-aliases) 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](#ii-path-expressions) or with the [`run` command](#5-custom-scripts).

```
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](#7-aliases) 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).



#### 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](https://fr.wikipedia.org/wiki/Extensible_Markup_Language) and [json](https://json.org/) are read/written using the go standard library (_cf. [json](https://golang.org/pkg/encoding/json/), [xml](https://golang.org/pkg/encoding/xml/)_).

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

- [yaml](https://en.wikipedia.org/wiki/YAML) with [go-yaml/yaml](https://github.com/go-yaml/yaml).
- [ini](https://en.wikipedia.org/wiki/INI_file) with [go-ini/ini](https://github.com/go-ini/ini).

-  [nginx configurations](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/) with [my own library](https://godoc.org/github.com/xdrm-brackets/nix-amer/internal/cnf/parser/nginx).
-  _and more to come..._



----

## Example

Launch the following command to install your server :

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

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



_myserver.build_

```
[ comment starts with opening brackets '['

[aliases]
alias sshd  /etc/ssh/sshd_config
alias nginx /etc/nginx/nginx.conf
alias sslh  /etc/default/sslh

[install packages]
install nginx ssh
install 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
```