diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..7e14437 --- /dev/null +++ b/Readme.md @@ -0,0 +1,219 @@ +# Unitctl +A command line utility to access and control running instances of NGINX Unit. + +# Building +First build with `cargo build`. Then copy `target/debug/unitctl` to wherever you want. + +# Usage +``` +λ target/debug/unitctl + +Usage: unitctl + +Commands: + start + status + api + schema + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help + -V, --version Print version +``` +``` +λ target/debug/unitctl start + +Usage: unitctl start --socket + +Options: + -s, --socket path to desired control socket + -h, --help Print help +``` +``` +λ target/debug/unitctl status + +Usage: unitctl status [OPTIONS] --uri + +Options: + -u, --uri URI the control API listens on + -s, --socket Unix Socket the control API listens on + -v, --verbose switch to trigger verbose behavior in libcurl + -h, --help Print help +``` +``` +λ target/debug/unitctl api + +Usage: unitctl api [OPTIONS] --uri + +Options: + -u, --uri URI for API operation + -s, --socket Unix Socket the control API listens on + -j, --json inline JSON data to post to API + -f, --file file containing data to post to API. + -d, --delete switch to trigger a delete operation on an API endpoint. + -v, --verbose switch to trigger verbose behavior in libcurl + -h, --help Print help +``` +``` +λ target/debug/unitctl schema + +Usage: unitctl schema --path + +Options: + -p, --path path for schema query + -h, --help Print help +``` + +# Examples +Getting started: +``` +λ target/debug/unitctl start -s /tmp + +Using default tag: latest +latest: Pulling from library/unit +Digest: sha256:bae510e7594ba1a68895859cc7fa79ed4231907820d46c4a859f5cbe25f85a7e +Status: Image is up to date for unit:latest +docker.io/library/unit:latest +e22783542fabc49a120edc84fc3a48830b8fec0bda16ab20ed0fac95c743486b +Congratulations! NGINX Unit now running at /tmp/control.unit.sock +NOTICE: Socket access is root only by default. Run chown. +Current directory mounted to /www in NGINX Unit container. +``` + +Healthy Status: +``` +λ target/debug/unitctl status -s /tmp/control.unit.sock -u 'http://localhost/' -v + +* Trying /tmp/control.unit.sock:0... +* Connected to localhost (/tmp/control.unit.sock) port 0 +> GET / HTTP/1.1 +Host: localhost +Accept: */* + +* Request completely sent off +< HTTP/1.1 200 OK +< Server: Unit/1.32.1 +< Date: Tue, 16 Apr 2024 00:32:37 GMT +< Content-Type: application/json +< Content-Length: 595 +< Connection: close +< +{ { + "certificates": {}, + "js_modules": {}, + "config": { + "listeners": { + "*:80": { + "pass": "routes" + } + }, + + "routes": [ + { + "match": { + "headers": { + "accept": "*text/html*" + } + }, + + "action": { + "share": "/usr/share/unit/welcome/welcome.html" + } + }, + { + "action": { + "share": "/usr/share/unit/welcome/welcome.md" + } + } + ] + }, + + "status": { + "connections": { + "accepted": 0, + "active": 0, + "idle": 0, + "closed": 0 + }, + + "requests": { + "total": 0 + }, + + "applications": {} + } +} +* Closing connection +``` + +Querying the API: +``` +λ target/debug/unitctl api -s /tmp/control.unit.sock -u 'http://localhost/config' -v + +* Trying /tmp/control.unit.sock:0... +* Connected to localhost (/tmp/control.unit.sock) port 0 +> GET /config HTTP/1.1 +Host: localhost +Accept: */* + +* Request completely sent off +< HTTP/1.1 200 OK +< Server: Unit/1.32.1 +< Date: Tue, 16 Apr 2024 00:34:31 GMT +< Content-Type: application/json +< Content-Length: 335 +< Connection: close +< +{ { + "listeners": { + "*:80": { + "pass": "routes" + } + }, + + "routes": [ + { + "match": { + "headers": { + "accept": "*text/html*" + } + }, + + "action": { + "share": "/usr/share/unit/welcome/welcome.html" + } + }, + { + "action": { + "share": "/usr/share/unit/welcome/welcome.md" + } + } + ] +} +* Closing connection +``` + +Getting API Documentation: +``` +λ target/debug/unitctl schema -p /status/connections/idle + +--- +summary: "Endpoint for the `idle` connections number" +get: + operationId: getStatusConnectionsIdle + summary: Retrieve the idle connections number + description: "Retrieves the `idle` connections number that represents Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + tags: + - status + responses: + "200": + description: "OK; the `idle` number exists in the configuration." + content: + application/json: + schema: + type: integer + examples: + Idle: + value: 4 +``` \ No newline at end of file diff --git a/src/main.rs b/src/main.rs index 32e2565..3f5de1c 100644 --- a/src/main.rs +++ b/src/main.rs @@ -127,7 +127,7 @@ struct SchemaArgs { required = true, help = "path for schema query" )] - path: String, + path: String } fn do_start(args: StartArgs) { @@ -233,6 +233,8 @@ fn get_schema(args: SchemaArgs) { let mut emitter = YamlEmitter::new(&mut out_str); emitter.dump(&pathspec).unwrap(); // dump the YAML object to a String } + + println!("{}", out_str); } fn main() {