270 lines
8.3 KiB
Markdown
270 lines
8.3 KiB
Markdown
# | nix-amer |
|
|
|
|
[](https://golang.org/doc/go1.11)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://goreportcard.com/report/git.xdrm.io/go/nix-amer)
|
|
[](https://coveralls.io/github/xdrm-brackets/nix-amer?branch=master)
|
|
[](https://drone.xdrm.io/xdrm-brackets/ci-test)
|
|
[](https://godoc.org/git.xdrm.io/go/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) Sections](#1-sections)
|
|
+ [2) Comments](#2-comments)
|
|
+ [3) Install/remove Packages](#3-installremove-packages)
|
|
+ [4) Setup configuration](#4-setup-configuration)
|
|
+ [5) Service management](#5-service-management)
|
|
+ [6) Custom scripts](#6-custom-scripts)
|
|
+ [7) Copy files](#7-copy-files)
|
|
+ [8) Aliases](#8-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 git.xdrm.io/go/nix-amer
|
|
```
|
|
|
|
> For those who don't know, it will load the project sources into `$GOPATH/src/git.xdrm.io/go/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 it you can check the syntax and validate instructions 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 nix-amer and run it with your build file. The rich and colorful command-line output will give you a good feedback to rapidly fix problems.
|
|
|
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
|
|
### II. Commands
|
|
|
|
Your whole setup remains in only one file. Each line contains one instruction, the list of instructions is listed below.
|
|
|
|
|
|
|
|
#### 1) Sections
|
|
|
|
Each instruction is enclosed in a section (_cf. ini file format_), a section definition stands on a line where the name of the section is surrounded by `[` and `]`. Each section is executed in parallel ; the special section named `pre` is executed before every other.
|
|
|
|
|
|
|
|
#### 2) Comments
|
|
|
|
Each line beginning with one of the following characters : `#` or `;` is considered a comment and is not interpreted.
|
|
|
|
|
|
|
|
#### 3) 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.
|
|
|
|
|
|
|
|
#### 4) 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.
|
|
|
|
|
|
|
|
|
|
#### 5) 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.
|
|
|
|
|
|
|
|
#### 6) 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](#8-aliases) it will resolve to its path
|
|
|
|
#### 7) Copy files
|
|
|
|
This instruction allows you to copy files.
|
|
|
|
```
|
|
copy <src> <dst>
|
|
```
|
|
|
|
Try to copy the file \<src\> to the path \<dst\>.
|
|
|
|
|
|
|
|
#### 8) 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](#8-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/git.xdrm.io/go/nix-amer/internal/cnf/parser/nginx).
|
|
- [bash sourced configurations]() with [my own library](https://godoc.org/git.xdrm.io/go/nix-amer/internal/cnf/parser/bash) (_e.g. ~/.bashrc_).
|
|
- _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_
|
|
|
|
```
|
|
# [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
|
|
```
|
|
|