nix-amer/README.md

267 lines
8.0 KiB
Markdown
Raw Permalink Normal View History

2018-11-06 13:01:05 +00:00
# | nix-amer |
2018-11-06 10:17:33 +00:00
2018-11-11 00:08:33 +00:00
[![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)
2018-11-13 12:10:55 +00:00
[![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=meta%2Fcircle-ci)](https://coveralls.io/github/xdrm-brackets/nix-amer?branch=meta%2Fcircle-ci)
[![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)
2018-11-11 00:08:33 +00:00
2018-11-06 13:01:05 +00:00
```yaml
name: nix-amer
version: 0.1.0
description: Configuration automation tool
author: xdrm-brackets
```
2018-11-06 10:19:09 +00:00
2018-11-06 13:01:05 +00:00
>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)
2018-11-13 13:23:36 +00:00
+ [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 -->
2018-11-06 13:01:05 +00:00
----
### I. How to use
2018-11-06 16:17:39 +00:00
#### 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
2018-11-06 16:17:39 +00:00
2018-11-06 13:01:05 +00:00
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
2018-11-06 13:01:05 +00:00
These instructions allow you to interact with the package system available on your system.
```
install <packages>
2018-11-06 13:01:05 +00:00
```
Install the listed packages. If more than one, use spaces to separate package names.
2018-11-06 13:01:05 +00:00
```
delete <packages>
2018-11-06 13:01:05 +00:00
```
Remove the listed packages. If more than one, use spaces to separate package names.
#### 3) Setup configuration
2018-11-06 13:01:05 +00:00
This instruction allow you to set fields of configuration files without the need of an editor and in a developer-readable manner.
2018-11-06 13:01:05 +00:00
```
set <expr> <content>
2018-11-06 13:01:05 +00:00
```
2018-11-06 16:17:39 +00:00
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.
2018-11-06 13:01:05 +00:00
#### 4) Service management
These instructions allow you to interact with the service system (_cf. [systemd](https://github.com/systemd/systemd)_).
2018-11-06 13:01:05 +00:00
```
service [enable|start|stop|restart|reload] <services>
2018-11-06 13:01:05 +00:00
```
Perform the action on services. If more than one, use spaces to separate service names.
2018-11-06 13:01:05 +00:00
2018-11-06 16:17:39 +00:00
2018-11-13 13:08:49 +00:00
#### 5) Custom scripts
2018-11-06 13:01:05 +00:00
2018-11-13 13:23:36 +00:00
This instruction allows you to use custom scripts for complex operations.
2018-11-06 13:01:05 +00:00
```
run <script>
2018-11-06 13:01:05 +00:00
```
2018-11-13 13:23:36 +00:00
Execute the executable located at the path \<script\>. If script is an [alias](#7-aliases) it will resolve to its path
2018-11-13 13:23:36 +00:00
#### 6) Copy files
2018-11-06 13:01:05 +00:00
2018-11-13 13:23:36 +00:00
This instruction allows you to copy files.
2018-11-13 13:23:36 +00:00
```
copy <src> <dst>
```
Try to copy the file \<src\> to the path \<dst\>.
#### 7) Aliases
2018-11-06 16:17:39 +00:00
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).
2018-11-06 16:17:39 +00:00
```
alias name /path/to.file
2018-11-06 16:17:39 +00:00
```
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.
2018-11-06 16:17:39 +00:00
2018-11-06 13:01:05 +00:00
----
2018-11-06 16:17:39 +00:00
### III. Path Expressions
2018-11-06 13:01:05 +00:00
#### 1) Syntax
The syntax is pretty fast-forward, it uses 2 levels (file, fields) to find your configuration line : `location_or_alias@fields`.
2018-11-06 13:01:05 +00:00
| Field | Description | Example |
2018-11-06 16:17:39 +00:00
| --------- | :----------------------------------- | -------------------------- |
2018-11-13 13:23:36 +00:00
| `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).
2018-11-06 16:17:39 +00:00
#### 2) File Formats
2018-11-07 10:56:53 +00:00
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
2018-11-11 18:10:11 +00:00
- [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).
2018-11-11 18:10:11 +00:00
2018-11-13 12:10:55 +00:00
- [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).
2018-11-07 10:56:53 +00:00
- _and more to come..._
2018-11-06 16:17:39 +00:00
----
## 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.
2018-11-06 16:17:39 +00:00
_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
2018-11-06 16:17:39 +00:00
[install packages]
install nginx ssh
install sslh
2018-11-06 16:17:39 +00:00
[nginx]
set nginx@http.gzip off
service enable nginx
service start nginx
2018-11-06 16:17:39 +00:00
[sshd]
set sshd@PermitRootLogin no
set sshd@PermitEmptyPasswords no
service enable sshd
service enable ssh
2018-11-06 16:17:39 +00:00
[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
2018-11-06 16:17:39 +00:00
```