Skip to content

Commit 161a16b

Browse files
wietmannwietmann
committed
Update Readme and add Galaxy metadata
1 parent 9d8ecf3 commit 161a16b

File tree

2 files changed

+177
-1
lines changed

2 files changed

+177
-1
lines changed

‎README.md‎

Lines changed: 146 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,152 @@
11
Ansible Role: Shadowsocks-Rust
22
==============================
33

4-
Ansible Role that installs and manages [shadowsocks-rust]().
4+
Ansible Role that installs and manages [shadowsocks-rust](https://github.com/shadowsocks/shadowsocks-rust) on Linux hosts.
5+
6+
Role downloads defined version of `shadowsocks-rust` from release pacge on GitHub, sets up process environment (create process user and group, add systemd unit files, add configuration files) and manages process instances via systemd. Currently `sslocal` and `ssserver` instanced service units are present.
7+
8+
By default, Musl build for x86_64 is installed.
9+
10+
Requirements
11+
------------
12+
13+
Python, Ansible >= 2.9
14+
15+
Role Variables
16+
--------------
17+
18+
|Variable|Deafule value|Description|
19+
|-|-|-|
20+
|`shadowsocks_rust_version`|`1.12.4`|Shadowsocks-rust version|
21+
|`shadowsocks_rust_bin_path`|`/usr/local/bin`|Path to directory where binaries will reside|
22+
|`shadowsocks_rust_linux_libc`|`musl`|Choose LibC version for Linux binary. See release page for specific version for available values|
23+
|`shadowsocks_rust_config_path`|`/etc/shadowsocks-rust`|Path to Shadowsocks-rust configuration files directory|
24+
|`shadowsocks_rust_user`|`shadowsocks-rust`|System user to run shadowsocks-rust process with|
25+
|`shadowsocks_rust_group`|`shadowsocks-rust`|System group to run shadowsocks-rust process with|
26+
|`shadowsocks_rust_config`|`[]`|List of Shadowsocks instances configurations|
27+
|`shadowsocks_rust_config[*].name`|-|Instance name (will be used as name for in systemd service after `@`)|
28+
|`shadowsocks_rust_config[*]state`|`present`|Whether to create or destroy instance. Available values: `present`, `absent`|
29+
|`shadowsocks_rust_config[*].type`|`server`|Instance type: `server`, `local`|
30+
|`shadowsocks_rust_config[*].config`|-|Dictionary representing Shadowsocks config file structure. See shadowsocks-rust documentation for available values.|
31+
32+
Dependencies
33+
------------
34+
35+
None.
36+
37+
Supported platforms
38+
-------------------
39+
40+
* RHEL 7, 8
41+
* Debian: 9, 10, 11
42+
* Ubuntu: 18.04, 20.04
43+
* Amazon Linux 2
44+
45+
**NB1**: Role should work on non-LTS Ubuntu releases, although not tested specifically.
46+
47+
Example Playbook
48+
----------------
49+
50+
Setup 2 different shadowsocks servers on one host:
51+
52+
```yaml
53+
---
54+
- hosts: all
55+
become: yes
56+
57+
vars:
58+
shadowsocks_rust_config:
59+
- name: server_home
60+
state: present
61+
type: server
62+
config:
63+
server: "0.0.0.0"
64+
server_port: 12345
65+
password: "VerySecretPassword1"
66+
timeout: 60
67+
method: "aes-256-gcm"
68+
fast_open: true
69+
- name: server_friends
70+
state: present
71+
type: server
72+
config:
73+
server: "0.0.0.0"
74+
server_port: 12346
75+
password: "VerySecretPassword2"
76+
timeout: 60
77+
method: "aes-256-gcm"
78+
fast_open: true
79+
_packages:
80+
"Debian":
81+
- xz-utils
82+
- zip
83+
- tar
84+
"RedHat":
85+
- xz
86+
- zip
87+
- tar
88+
89+
- name: Install dependancies
90+
package:
91+
name: "{{ _packages[ansible_os_family] }}"
92+
state: present
93+
94+
roles:
95+
- role: wietmann.shadowsocks-rust
96+
```
97+
98+
Client (`sslocal`)
99+
```yaml
100+
---
101+
- hosts: all
102+
become: yes
103+
104+
vars:
105+
shadowsocks_rust_config:
106+
- name: nl_vps1_home
107+
state: present
108+
type: local
109+
config:
110+
server: "somewhere.tld"
111+
server_port: 12345
112+
password: "VerySecretPassword1"
113+
method: "aes-256-gcm"
114+
local_port: 1081
115+
116+
roles:
117+
- role: wietmann.shadowsocks-rust
118+
```
119+
120+
Testing
121+
-------
122+
123+
This role uses [Molecule](https://molecule.readthedocs.io/en/stable/) for testing. Molecule is run against Docker containers with enabled systemd support (see `default` scenario). Docker Engine, `docker` library and `molecule-docker` driver Python packages should be installed on controller host.
124+
125+
Preferred way to test role for compatibility with different versions of Ansible is to use [Tox](https://tox.wiki/en/stable/). See `tox.ini` for the full list of supported Ansible versions.
126+
127+
Run tests for all environments:
128+
```
129+
tox
130+
```
131+
132+
List available environments:
133+
```
134+
tox -l
135+
```
136+
137+
Run tests only for specific environment (e.g. Ansible 2.9):
138+
```
139+
tox -e py3-ansible29
140+
```
141+
142+
Run only specific Molecule subcommand (e.g. `molecule verify`):
143+
144+
```
145+
# All test environments
146+
tox -- molecule verify
147+
# Specific test environments
148+
tox -e py3-ansible29 -- molecule verify
149+
```
5150

6151
License
7152
-------

‎meta/main.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
galaxy_info:
3+
role_name: shadowsocks_rust
4+
namespace: wietmann
5+
author: Dmitry Danilov
6+
description: Setup Shadowsocks-rust
7+
license: MIT
8+
min_ansible_version: 2.9
9+
10+
platforms:
11+
- name: EL
12+
versions:
13+
- 7
14+
- 8
15+
- name: Debian
16+
versions:
17+
- stretch
18+
- buster
19+
- bullseye
20+
- name: Ubuntu
21+
versions:
22+
- bionic
23+
- focal
24+
25+
galaxy_tags:
26+
- linux
27+
- shadowsocks
28+
- shadowsocks-rust
29+
- proxy
30+
31+
dependencies: []

0 commit comments

Comments
 (0)