diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ea8c4bf --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/target diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..b6f8493 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,380 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "anstream" +version = "0.6.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d96bd03f33fe50a863e394ee9718a706f988b9079b20c3784fb726e7678b62fb" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8901269c6307e8d93993578286ac0edf7f195079ffff5ebdeea6a59ffb7e36bc" + +[[package]] +name = "anstyle-parse" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c75ac65da39e5fe5ab759307499ddad880d724eed2f6ce5b5e8a26f4f387928c" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e28923312444cdd728e4738b3f9c9cac739500909bb3d3c94b43551b16517648" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1cd54b81ec8d6180e24654d0b371ad22fc3dd083b6ff8ba325b72e00c87660a7" +dependencies = [ + "anstyle", + "windows-sys", +] + +[[package]] +name = "bytes" +version = "1.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "514de17de45fdb8dc022b1a7975556c53c86f9f0aa5f534b98977b171857c2c9" + +[[package]] +name = "cc" +version = "1.0.94" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "17f6e324229dc011159fcc089755d1e2e216a90d43a7dea6853ca740b84f35e7" + +[[package]] +name = "clap" +version = "4.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "90bc066a67923782aa8515dbaea16946c5bcc5addbd668bb80af688e53e548a0" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae129e2e766ae0ec03484e609954119f123cc1fe650337e155d03b022f24f7b4" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "528131438037fd55894f62d6e9f068b8f45ac57ffa77517819645d10aed04f64" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "98cc8fbded0c607b7ba9dd60cd98df59af97e84d24e49c8557331cfc26d301ce" + +[[package]] +name = "colorchoice" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "acbf1af155f9b9ef647e42cdc158db4b64a1b61f743629225fde6f3e0be2a7c7" + +[[package]] +name = "curl" +version = "0.4.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e2161dd6eba090ff1594084e95fd67aeccf04382ffea77999ea94ed42ec67b6" +dependencies = [ + "curl-sys", + "libc", + "openssl-probe", + "openssl-sys", + "schannel", + "socket2", + "windows-sys", +] + +[[package]] +name = "curl-sys" +version = "0.4.72+curl-8.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29cbdc8314c447d11e8fd156dcdd031d9e02a7a976163e396b548c03153bc9ea" +dependencies = [ + "cc", + "libc", + "libz-sys", + "openssl-sys", + "pkg-config", + "vcpkg", + "windows-sys", +] + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "http" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "21b9ddb458710bc376481b842f5da65cdf31522de232c1ca8146abce2a358258" +dependencies = [ + "bytes", + "fnv", + "itoa", +] + +[[package]] +name = "itoa" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" + +[[package]] +name = "libc" +version = "0.2.153" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c198f91728a82281a64e1f4f9eeb25d82cb32a5de251c6bd1b5154d63a8e7bd" + +[[package]] +name = "libz-sys" +version = "1.1.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e143b5e666b2695d28f6bca6497720813f699c9602dd7f5cac91008b8ada7f9" +dependencies = [ + "cc", + "libc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "linked-hash-map" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f" + +[[package]] +name = "openssl-probe" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff011a302c396a5197692431fc1948019154afc178baf7d8e37367442a4601cf" + +[[package]] +name = "openssl-sys" +version = "0.9.102" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c597637d56fbc83893a35eb0dd04b2b8e7a50c91e64e9493e398b5df4fb45fa2" +dependencies = [ + "cc", + "libc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "pkg-config" +version = "0.3.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d231b230927b5e4ad203db57bbcbee2802f6bce620b1e4a9024a07d94e2907ec" + +[[package]] +name = "proc-macro2" +version = "1.0.80" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a56dea16b0a29e94408b9aa5e2940a4eedbd128a1ba20e8f7ae60fd3d465af0e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fa76aaf39101c457836aec0ce2316dbdc3ab723cdda1c6bd4e6ad4208acaca7" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "schannel" +version = "0.1.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fbc91545643bcf3a0bbb6569265615222618bdf33ce4ffbbd13c4bbd4c093534" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "socket2" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05ffd9c0a93b7543e062e759284fcf5f5e3b098501104bfbdde4d404db792871" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "syn" +version = "2.0.59" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a6531ffc7b071655e4ce2e04bd464c4830bb585a61cabb96cf808f05172615a" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "unicode-ident" +version = "1.0.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b" + +[[package]] +name = "unitctl" +version = "0.1.0" +dependencies = [ + "clap", + "curl", + "http", + "yaml-rust", +] + +[[package]] +name = "utf8parse" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "711b9620af191e0cdc7468a8d14e709c3dcdb115b36f838e601583af800a370a" + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-targets" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f0713a46559409d202e70e28227288446bf7841d3211583a4b53e3f6d96e7eb" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7088eed71e8b8dda258ecc8bac5fb1153c5cffaf2578fc8ff5d61e23578d3263" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9985fd1504e250c615ca5f281c3f7a6da76213ebd5ccc9561496568a2752afb6" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "88ba073cf16d5372720ec942a8ccbf61626074c6d4dd2e745299726ce8b89670" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "87f4261229030a858f36b459e748ae97545d6f1ec60e5e0d6a3d32e0dc232ee9" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db3c2bf3d13d5b658be73463284eaf12830ac9a26a90c717b7f771dfe97487bf" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e4246f76bdeff09eb48875a0fd3e2af6aada79d409d33011886d3e1581517d9" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "852298e482cd67c356ddd9570386e2862b5673c85bd5f88df9ab6802b334c596" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bec47e5bfd1bff0eeaf6d8b485cc1074891a197ab4225d504cb7a1ab88b02bf0" + +[[package]] +name = "yaml-rust" +version = "0.4.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56c1936c4cc7a1c9ab21a1ebb602eb942ba868cbd44a99cb7cdc5892335e1c85" +dependencies = [ + "linked-hash-map", +] diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..d4121dd --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "unitctl" +version = "0.1.0" +edition = "2021" +about = "A client to operate the NGINX Unit control API" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +clap = { version = "4.5.4", features = ["derive"] } +curl = "0.4.46" +http = "1.1.0" +yaml-rust = "0.4.5" diff --git a/src/main.rs b/src/main.rs new file mode 100644 index 0000000..32e2565 --- /dev/null +++ b/src/main.rs @@ -0,0 +1,252 @@ +use clap::{ + Args, Parser, Subcommand +}; +use std::{ + fs, env, + io::Read, + process::Command +}; +use yaml_rust::{ + YamlLoader, YamlEmitter +}; + +use curl::easy::Easy; +use http::Uri; + +const OAI_SPEC: &str = include_str!("../unit-openapi.yaml"); + +#[derive(Parser)] +#[command(name = "unitctl")] +#[command(version, about, long_about = None)] +struct Cli { + #[command(subcommand)] + command: Commands, +} + +#[derive(Subcommand, Clone)] +enum Commands { + #[command(arg_required_else_help = true)] + Start(StartArgs), + + // TODO : Modify status call to point to some specific API endpoint + #[command(arg_required_else_help = true)] + Status(StatusArgs), + + // TODO : Validate calls with openapi spec + // TODO : Access over SSH + // TODO : Access within docker containers + // TODO : Support custom certs probably + // TODO : Turn on netrc support probably? + #[command(arg_required_else_help = true)] + API(APIArgs), + + // TODO : Load spec from submodule instead of duplicate file + // TODO : Use an actual OpenAPI spec parser + #[command(arg_required_else_help = true)] + Schema(SchemaArgs), +} + +#[derive(Args, Clone)] +struct StartArgs { + #[arg( + short, long, + required = true, + help = "path to desired control socket" + )] + socket: String +} + +#[derive(Args, Clone)] +struct StatusArgs { + #[arg( + short, long, + required = true, + help = "URI the control API listens on" + )] + uri: String, + + #[arg( + short, long, + help = "Unix Socket the control API listens on" + )] + socket: Option, + + #[arg( + short, long, + help = "switch to trigger verbose behavior in libcurl" + )] + verbose: bool, +} + +#[derive(Args, Clone)] +struct APIArgs { + #[arg( + short, long, + required = true, + help = "URI for API operation" + )] + uri: String, + + #[arg( + short, long, + help = "Unix Socket the control API listens on" + )] + socket: Option, + + #[arg( + short, long, + conflicts_with = "file", + help = "inline JSON data to post to API" + )] + json: Option, + + #[arg( + short, long, + help = "file containing data to post to API." + )] + file: Option, + + #[arg( + short, long, + help = "switch to trigger a delete operation on an API endpoint.", + conflicts_with_all = ["file", "json"] + )] + delete: bool, + + #[arg( + short, long, + help = "switch to trigger verbose behavior in libcurl" + )] + verbose: bool, +} + +#[derive(Args, Clone)] +struct SchemaArgs { + #[arg( + short, long, + required = true, + help = "path for schema query" + )] + path: String, +} + +fn do_start(args: StartArgs) { + Command::new("docker") + .args(["pull", "unit"]) + .spawn() + .expect("failed to call Docker") + .wait() + .expect("expected Docker to succeed"); + + let appmount = format!( + "type=bind,src={},dst=/www", + env::current_dir().unwrap().display() + ); + + let sockmount = format!( + "type=bind,src={},dst=/var/run/", + args.socket + ); + + Command::new("docker") + .args(["run", "-d", + "--mount", appmount.as_str(), + "--mount", sockmount.as_str(), + "--network", "host", "unit"]) + .spawn() + .expect("failed to call Docker") + .wait() + .expect("expected Docker to succeed"); + + println!("Congratulations! NGINX Unit now running at {}/control.unit.sock", args.socket); + println!("NOTICE: Socket access is root only by default. Run chown."); + println!("Current directory mounted to /www in NGINX Unit container."); +} + +fn get_status(args: StatusArgs) { + do_api_call(APIArgs { + socket: args.socket, + uri: args.uri, + verbose: args.verbose, + json: None, file: None, + delete: false, + }) +} + +fn do_api_call(args: APIArgs) { + let mut curl = Easy::new(); + + if let Some(path) = args.socket { + curl.unix_socket(path.as_str()).unwrap(); + } + curl.url(args.uri.as_str()).unwrap(); + curl.verbose(args.verbose).unwrap(); + + let contents: Option; + if let Some(path) = args.file { + contents = Some(fs::read_to_string(path) + .expect("Should have been able to read the file")); + } else { + contents = args.json; + } + + if let None = contents { + curl.get(true).unwrap(); + if let Err(e) = curl.perform() { + eprintln!("error in API call: {}", e) + } + } else { + curl.post(true).unwrap(); + curl.post_field_size(contents.clone().unwrap().len() as u64).unwrap(); + let mut transfer = curl.transfer(); + transfer.read_function(|buf| { + Ok(contents.clone().unwrap().as_bytes().read(buf).unwrap_or(0)) + }).unwrap(); + if let Err(e) = transfer.perform() { + eprintln!("error in API call: {}", e) + } + } +} + +fn get_schema(args: SchemaArgs) { + let maybe_path = args.path.parse::(); + if let Err(e) = maybe_path { + eprintln!("Error: couldn't load path from uri: {}", e); + return + } + let path = maybe_path.unwrap(); + + let spec = YamlLoader::load_from_str(OAI_SPEC).unwrap(); + if spec[0]["paths"].is_badvalue() { + eprintln!("Error: no paths in OpenAPI spec!") + } + if spec[0]["paths"][path.path()].is_badvalue() { + eprintln!("Error: requested path not found."); + eprintln!("\tConsider checking manually:"); + eprintln!("\thttps://github.com/nginx/unit/blob/master/docs/unit-openapi.yaml"); + return; + } + + let pathspec = spec[0]["paths"][path.path()].clone(); + let mut out_str = String::new(); + { + let mut emitter = YamlEmitter::new(&mut out_str); + emitter.dump(&pathspec).unwrap(); // dump the YAML object to a String + } +} + +fn main() { + let call = Cli::parse(); + match call.command { + Commands::Start(args) => do_start(args), + Commands::Status(args) => get_status(args), + Commands::API(args) => do_api_call(args), + Commands::Schema(args) => get_schema(args), + } +} + +#[test] +fn verify_cli() { + use clap::CommandFactory; + Cli::command().debug_assert() +} \ No newline at end of file diff --git a/unit-openapi.yaml b/unit-openapi.yaml new file mode 100644 index 0000000..eceaf4f --- /dev/null +++ b/unit-openapi.yaml @@ -0,0 +1,6389 @@ +openapi: 3.0.0 +info: + title: "NGINX Unit 1.32.0" + description: "NGINX Unit is a lightweight and versatile application runtime + that provides the essential components for your web application as a + single open-source server: running application code, serving static assets, + handling TLS and request routing. + + \n\n**Important**: Unit's API is designed to expose any part of its + configuration as an addressable endpoint. Suppose a JSON + object is stored at `/config/listeners/`:\n\n + + ```json + { + \"*:8080\": { + \"pass\": \"applications/wp_emea_dev\" + } + } + ```\n + + Here, `/config/listeners/*:8080` and `/config/listeners/*:8080/pass` + are also endpoints. Generally, object options are addressable by + their names, array items—by their indexes (`/array/0/`). + + + \n\n**Note**: By default, Unit is configured through a UNIX domain + socket. To use this specification with OpenAPI tools interactively, + [start](https://unit.nginx.org/howto/source/#source-startup) Unit + with a TCP port as the control socket." + + contact: + name: "Unit project" + email: "unit-owner@nginx.org" + url: "https://unit.nginx.org/" + + license: + name: "Apache 2.0" + url: "https://www.apache.org/licenses/LICENSE-2.0.html" + + version: 0.2.0 + +servers: + - url: http://{server}:{port} + variables: + server: + default: "localhost" + + port: + default: "8080" + +# -- PATHS -- + +paths: + /certificates: + summary: "Endpoint for the `certificates` object" + get: + operationId: getCerts + summary: "Retrieve the certificates object" + description: "Retrieves the entire `/certificates` section that represents + Unit's [stored certificates](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + responses: + "200": + description: "OK; the `certificates` object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/cert" + + examples: + example1: + $ref: "#/components/examples/cert" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}: + summary: "Endpoint for the certificate bundle object" + get: + operationId: getCertBundle + summary: "Retrieve the certificate bundle object" + description: "Retrieves the bundle description that represents + Unit's [stored certificate bundle] + (https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate bundle object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundle" + + examples: + example1: + $ref: "#/components/examples/certBundle" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: putCertBundle + summary: "Create or overwrite the actual certificate bundle" + description: "Creates or overwrites the [stored certificate bundle] + (https://unit.nginx.org/certificates/) in Unit." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/bundleName" + + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + /certificates/{bundleName}/key: + summary: "Endpoint for the certificate bundle key" + get: + operationId: getCertBundleKey + summary: "Retrieve the certificate bundle key type" + description: "Retrieves the bundle key type from a + [stored certificate bundle](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate bundle key type exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + Key: + value: "RSA (4096 bits)" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain: + summary: "Endpoint for the certificate bundle chain" + get: + operationId: getCertBundleChain + summary: "Retrieve the certificate bundle chain" + description: "Retrieves the bundle chain from a + [stored certificate bundle](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate bundle chain exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundleChain" + + examples: + example1: + $ref: "#/components/examples/certBundleChain" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}: + summary: "Endpoint for the certificate object in the chain array" + get: + operationId: getCertBundleChainCert + summary: "Retrieve certificate object from the chain array" + description: "Retrieves the individual certificate from a + [stored certificate bundle](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundleChainCert" + + examples: + example1: + $ref: "#/components/examples/certBundleChainCert" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject: + summary: "Endpoint for the certificate subject object" + get: + operationId: getCertBundleChainCertSubj + summary: "Retrieve the subject from the certificate object" + description: "Retrieves the subject from a + [stored certificate](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundleChainCertSubj" + + examples: + example1: + $ref: "#/components/examples/certBundleChainCertSubj" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/common_name: + summary: "Endpoint for the certificate's common name" + get: + operationId: getCertBundleChainCertSubjCN + summary: "Retrieve the common name from the certificate subject" + description: "Retrieves the common name from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's common name exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + CN: + value: "example.com" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/country: + summary: "Endpoint for the certificate's country of issue" + get: + operationId: getCertBundleChainCertSubjCountry + summary: "Retrieve the country code from the certificate subject" + description: "Retrieves the country code from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's country code exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + Country: + value: "US" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/state_or_province: + summary: "Endpoint for the certificate's state or province of issue" + get: + operationId: getCertBundleChainCertSubjState + summary: "Retrieve the state or province code from the + certificate subject" + + description: "Retrieves the state or province code from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's state or province code + exists in the configuration." + + content: + application/json: + schema: + type: string + + examples: + StateProvince: + value: "CA" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/organization: + summary: "Endpoint for the certificate's designated organization" + get: + operationId: getCertBundleChainCertSubjOrg + summary: "Retrieve the organization name from the certificate subject" + description: "Retrieves the organization name from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's organization name exists + in the configuration." + + content: + application/json: + schema: + type: string + + examples: + Org: + value: "Acme, Inc." + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/alt_names: + summary: "Endpoint for the certificate's alternative names" + get: + operationId: getCertBundleChainCertSubjAltArray + summary: "Retrieve the alternative names array from the + certificate subject" + + description: "Retrieves the alternative names array from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's alternative names array + exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/stringArray" + + examples: + AltNames: + value: + - "example.com" + - "www.example.com" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/subject/alt_names/{arrayIndex2}: + summary: "Endpoint for the certificate's alternative name" + get: + operationId: getCertBundleChainCertSubjAlt + summary: "Retrieve an alternative name from the certificate subject" + description: "Retrieves an alternative name from a + [stored certificate's subject](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/arrayIndex2" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate subject's alternative name exists + in the configuration." + + content: + application/json: + schema: + type: string + + examples: + AltName: + value: "example.com" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/issuer: + summary: "Endpoint for the certificate issuer object" + get: + operationId: getCertBundleChainCertIssuer + summary: "Retrieve the issuer object from the certificate object" + description: "Retrieves the issuer object from a + [stored certificate](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate issuer object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundleChainCertIssuer" + + examples: + example1: + $ref: "#/components/examples/certBundleChainCertIssuer" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/issuer/common_name: + summary: "Endpoint for the certificate issuer's common name" + get: + operationId: getCertBundleChainCertIssuerCN + summary: "Retrieve the common name from the certificate issuer" + description: "Retrieves the common name from a + [stored certificate's issuer](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate issuer's common name exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + CN: + value: "intermediate.ca.example.com" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/issuer/country: + summary: "Endpoint for the certificate issuer's country of issue" + get: + operationId: getCertBundleChainCertissuerCountry + summary: "Retrieve the country code from the certificate issuer" + description: "Retrieves the country code from a + [stored certificate's issuer](https://unit.nginx.org/certificates/)." + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate issuer's country code exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + Country: + value: "US" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/issuer/state_or_province: + summary: "Endpoint for the certificate issuer's state or province of issue" + get: + operationId: getCertBundleChainCertIssuerState + summary: "Retrieve the state or province code from the certificate issuer" + description: "Retrieves the state or province code from a + [stored certificate's issuer](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate issuer's state or province code + exists in the configuration." + + content: + application/json: + schema: + type: string + + examples: + StateProvince: + value: "CA" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/issuer/organization: + summary: "Endpoint for the certificate issuer's designated organization" + get: + operationId: getCertBundleChainCertIssuerOrg + summary: "Retrieve the organization name from the certificate issuer" + description: "Retrieves the organization name from a + [stored certificate's issuer](https://unit.nginx.org/certificates/)." + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate issuer's organization name exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + Org: + value: "Acme Certification Authority" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/validity: + summary: "Endpoint for the certificate validity object" + get: + operationId: getCertBundleChainCertValid + summary: "Retrieve the validity object from the certificate object" + description: "Retrieves the validity object from a + [stored certificate](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the certificate validity object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/certBundleChainCertValidity" + + examples: + example1: + $ref: "#/components/examples/certBundleChainCertValidity" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/validity/since: + summary: "Endpoint for the certificate validity's starting time" + get: + operationId: getCertBundleChainCertValidSince + summary: "Retrieve the starting time of certificate validity" + description: "Retrieves the starting time of a + [stored certificate's validity](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the starting time of certificate validity exists + in the configuration." + + content: + application/json: + schema: + type: string + + examples: + DateTime: + value: "Sep 18 19:46:19 2022 GMT" + + "404": + $ref: "#/components/responses/responseNotFound" + + /certificates/{bundleName}/chain/{arrayIndex}/validity/until: + summary: "Endpoint for the certificate validity's ending time" + get: + operationId: getCertBundleChainCertValidUntil + summary: "Retrieve the ending time of certificate validity" + description: "Retrieves the ending time of a + [stored certificate's validity](https://unit.nginx.org/certificates/)." + + tags: + - certificates + + parameters: + - $ref: "#/components/parameters/arrayIndex" + - $ref: "#/components/parameters/bundleName" + + responses: + "200": + description: "OK; the ending time of certificate validity exists + in the configuration." + + content: + application/json: + schema: + type: string + + examples: + DateTime: + value: "Sep 18 19:46:19 2022 GMT" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config: + summary: "Endpoint for the `config` object" + get: + operationId: getConfig + summary: "Retrieve the config" + description: "Retrieves the `config` object that represents Unit's + [configuration](https://unit.nginx.org/configuration)." + + tags: + - config + + responses: + "200": + description: "OK; the `config` object exists in the + configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/config" + + examples: + example1: + $ref: "#/components/examples/config" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateConfig + summary: "Create or overwrite the config" + description: "Creates or overwrites the entire `config` object." + tags: + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/config" + + examples: + example1: + $ref: "#/components/examples/config" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteConfig + summary: "Delete the config object" + description: "Deletes the entire `config` object." + tags: + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/access_log: + summary: "Endpoint for the `access_log` object" + get: + operationId: getAccessLog + summary: "Retrieve the access log" + description: "Retrieves the `access_log` entity that represents Unit's + [access log](https://unit.nginx.org/configuration/#access-log)." + + tags: + - access log + - config + + responses: + "200": + description: "OK; the `access_log` entity exists in the + configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configAccessLog" + + examples: + example1: + $ref: "#/components/examples/configAccessLogBasic" + + example2: + $ref: "#/components/examples/configAccessLogComplex" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateAccessLog + summary: "Create or overwrite the access log" + description: "Creates or overwrites the entire `access_log` entity." + tags: + - access log + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configAccessLog" + + examples: + example1: + $ref: "#/components/examples/configAccessLogBasic" + + example2: + $ref: "#/components/examples/configAccessLogComplex" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteAccessLog + summary: "Delete the access log" + description: "Deletes the entire `access_log` section." + tags: + - access log + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/access_log/format: + summary: "Endpoint for the `format` access log option" + get: + operationId: getAccessLogFormat + summary: "Retrieve the access log format option" + description: "Retrieves the `format` option that represents Unit's + [access log format](https://unit.nginx.org/configuration/#access-log) + in the `access_log` object." + + tags: + - access log + - config + + responses: + "200": + description: "OK; the `format` option exists in the configuration." + + content: + application/json: + schema: + type: string + + examples: + format: + value: '$remote_addr - - [$time_local] "$request_line" $status + $body_bytes_sent "$header_referer" "$header_user_agent"' + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateAccessLogFormat + summary: "Create or overwrite the access log format" + description: "Creates or overwrites the `format` option in the + `access_log` object." + + tags: + - access log + - config + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + format: + value: '$remote_addr - - [$time_local] "$request_line" $status + $body_bytes_sent "$header_referer" "$header_user_agent"' + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteAccessLogFormat + summary: "Delete the access log format" + description: "Deletes the `format` option from the `access_log` object." + tags: + - access log + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/access_log/path: + summary: "Endpoint for the `path` access log option" + get: + operationId: getAccessLogPath + summary: "Retrieve the access log path option" + description: "Retrieves the `path` option that represents Unit's + [access log path](https://unit.nginx.org/configuration/#access-log) + in the `access_log` object." + + tags: + - access log + - config + + responses: + "200": + description: "OK; the `path` option exists in the configuration." + + content: + application/json: + schema: + type: string + + examples: + path: + value: "/var/log/unit/access.log" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateAccessLogPath + summary: "Create or overwrite the access log path" + description: "Creates or overwrites the `path` option in the `access_log` + object." + + tags: + - access log + - config + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + path: + value: "/var/log/unit/access.log" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteAccessLogPath + summary: "Delete the access log path" + description: "Deletes the `path` option from the `access_log` object." + tags: + - access log + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/applications: + summary: "Endpoint for the `applications` object in the configuration" + get: + operationId: getApplications + summary: "Retrieve the applications object" + description: "Retrieves the `applications` object that represents Unit's + [applications](https://unit.nginx.org/configuration/#applications)." + tags: + - applications + - config + + responses: + "200": + description: "OK; the `applications` object exists in the + configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configApplications" + + examples: + example1: + $ref: "#/components/examples/configApplications" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateApplications + summary: "Overwrite the applications object" + description: "Overwrites the `applications` object in the configuration." + tags: + - applications + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configApplications" + + examples: + example1: + $ref: "#/components/examples/configApplications" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteApplications + summary: "Delete the applications object" + description: "Deletes the `applications` object from the configuration." + tags: + - applications + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/applications/{appName}: + summary: "Endpoint for an application object in the configuration" + + parameters: + - $ref: "#/components/parameters/appName" + + get: + operationId: getApplication + summary: "Retrieve an application object" + description: "Retrieves the `{appName}` object that represents an + [application](https://unit.nginx.org/configuration/#applications) + in Unit's control API." + + tags: + - applications + - config + + responses: + "200": + description: "OK; the `{appName}` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configApplication" + + examples: + example1: + $ref: "#/components/examples/configApplication" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateApplication + summary: "Create or overwrite the application object" + description: "Creates or overwrites the `{appName}` object in the + configuration." + + tags: + - applications + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configApplication" + + examples: + example1: + $ref: "#/components/examples/configApplication" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteApplication + summary: "Delete the application object" + description: "Deletes the `{appName}` object from the configuration." + tags: + - applications + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /control/applications/{appName}/restart: + summary: "Endpoint for the `applications/{appName}/restart` option" + get: + operationId: getAppRestart + summary: "Restart the {appName} application" + description: "Tells Unit to [restart] + (https://unit.nginx.org/configuration/#process-management) + the application identified by `{appName}`." + + tags: + - apps + - control + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `{appName}` application was gracefully + restarted." + + content: + application/json: + schema: + $ref: "#/components/schemas/jsonSuccessMessage" + + example: + success: "Ok" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners: + summary: "Endpoint for the `listeners` object" + get: + operationId: getListeners + summary: "Retrieve all the listeners" + description: "Retrieves the `listeners` object whose options represent + individual [listeners](https://unit.nginx.org/configuration/#listeners); + each is a unique combination of a host IP address (or a `*` wildcard to + match any host IP addresses) and a port." + + tags: + - listeners + - config + + responses: + "200": + description: "OK; the `listeners` object exists in the configuration." + content: + application/json: + schema: + $ref: "#/components/schemas/configListeners" + + examples: + example1: + $ref: "#/components/examples/configListeners" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListeners + summary: "Create or overwrite all the listeners" + description: "Creates or overwrites the entire `listeners` section with + an object whose options represent individual listeners; each is a unique + combination of a host IP address (or a `*` wildcard to match any host IP + addresses) and a port." + + tags: + - listeners + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListeners" + + examples: + example1: + $ref: "#/components/examples/configListenerSimple" + + example2: + $ref: "#/components/examples/configListeners" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListeners + summary: "Delete all the listeners" + description: "Deletes the entire `listeners` section." + tags: + - listeners + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}: + summary: "Endpoint for a `listeners/{listenerName}` object that + represents a listener" + + get: + operationId: getListener + summary: "Retrieve a listener object" + description: "Retrieves the `{listenerName}` object that configures a + [listener](https://unit.nginx.org/configuration/#listeners)." + + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `{listenerName}` object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListener" + + examples: + example1: + $ref: "#/components/examples/configListenerSimple" + + example2: + $ref: "#/components/examples/configListenerComplex" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListener + summary: "Create or overwrite a listener object" + description: "Creates or overwrites the `{listenerName}` object." + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListener" + + examples: + example1: + $ref: "#/components/examples/configListenerSimple" + + example2: + $ref: "#/components/examples/configListenerComplex" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListener + summary: "Delete a listener object" + description: "Deletes the `{listenerName}` object." + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/pass: + summary: "Endpoint for the `listeners/{listenerName}/pass` option" + get: + operationId: getListenerPass + summary: "Retrieve the pass option in a listener" + description: "Retrieves the `pass` option that configures the destination + where the `{listenerName}` listener object + [passes its requests](https://unit.nginx.org/configuration/#listeners)." + + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `pass` option exists in the configuration." + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerPassApp" + + example2: + $ref: "#/components/examples/configListenerPassRoute" + + example3: + $ref: "#/components/examples/configListenerPassAppTarget" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerPass + summary: "Update the pass option in a listener" + description: "Overwrites the `pass` option." + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerPassApp" + + example2: + $ref: "#/components/examples/configListenerPassRoute" + + example3: + $ref: "#/components/examples/configListenerPassAppTarget" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + /config/listeners/{listenerName}/tls: + summary: "Endpoint for the `listeners/{listenerName}/tls` object" + get: + operationId: getListenerTls + summary: "Retrieve the tls object in a listener" + description: "Retrieves the `tls` object that configures [TLS settings] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + for the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `tls` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTls" + + examples: + example1: + $ref: "#/components/examples/configListenerTls" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerTls + summary: "Create or overwrite the tls object in a listener" + description: "Creates or overwrites the entire `tls` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTls" + + examples: + example1: + $ref: "#/components/examples/configListenerTls" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTls + summary: "Delete the tls object in a listener" + description: "Deletes the `tls` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/conf_commands: + summary: "Endpoint for the `listeners/{listenerName}/tls/conf_commands` + object" + + get: + operationId: listListenerTlsConfCommands + summary: "Retrieve the conf_commands object in a listener" + description: "Retrieves the `conf_commands` object that sets + [TLS configuration commands] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + for the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `conf_commands` object exists in the + configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsConfCommands" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsConfCommands" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerTlsConfCommands + summary: "Create or overwrite the conf_commands object in a listener" + description: "Creates or overwrites the entire `conf_commands` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsConfCommands" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsConfCommands" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsConfCommands + summary: "Delete the conf_commands object in a listener" + description: "Deletes the `conf_commands` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/session: + summary: "Endpoint for the `listeners/{listenerName}/tls/session` object" + get: + operationId: getListenerTlsSession + summary: "Retrieve the session object in a listener" + description: "Retrieves the `session` object that configures + [TLS session settings] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + for the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `session` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsSession" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSession" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerTlsSession + summary: "Create or overwrite the session object in a listener" + description: "Creates or overwrites the entire `session` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsSession" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSession" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsSession + summary: "Delete the session object in a listener" + description: "Deletes the `session` object." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/session/tickets: + summary: "Endpoint for the `listeners/{listenerName}/session/tickets` + object" + + get: + operationId: listListenerTlsSessionTickets + summary: "Retrieve the tickets option in a listener" + description: "Retrieves the `tickets` option that lists + [TLS session ticket keys] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + used with the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `tickets` option exists in the configuration." + + content: + application/jsons: + schema: + $ref: "#/components/schemas/configListenerTlsSessionTickets" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSessionTicketsBool" + + example2: + $ref: "#/components/examples/configListenerTlsSessionTicketsString" + + example3: + $ref: "#/components/examples/configListenerTlsSessionTicketsArray" + + "404": + $ref: "#/components/responses/responseNotFound" + + post: + operationId: insertListenerTlsSessionTicket + summary: "Add a new tickets array item in a listener" + description: "Adds a new session ticket key to the end of the `tickets` + string array that lists [session ticket keys] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + configured earlier." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSessionTicketsString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + put: + operationId: updateListenerTlsSessionTickets + summary: "Create or overwrite the tickets option in a listener" + description: "Creates or overwrites the entire `tickets` option with a + boolean, string, or string array that configures [session ticket keys] + (https://unit.nginx.org/configuration/#ssl-tls-configuration) + used with the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsSessionTickets" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSessionTicketsBool" + + example2: + $ref: "#/components/examples/configListenerTlsSessionTicketsString" + + example3: + $ref: "#/components/examples/configListenerTlsSessionTicketsArray" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsSessionTickets + summary: "Delete the tickets option in a listener" + description: "Deletes the `tickets` option." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/session/tickets/{arrayIndex}: + summary: "Endpoint for the `listeners/{listenerName}/tls/certificate` + object" + + get: + operationId: getListenerTlsSessionTicket + summary: "Retrieve a ticket array item in a listener" + description: "Retrieves the `{arrayIndex}`th item from the `tickets` + string array." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + description: "OK; the ticket key at `{arrayIndex}` exists in the + configuration." + + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSessionTicketsString" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerTlsSessionTicket + summary: "Create or overwrite a ticket array item in a listener" + description: "Overwrites a single `tickets` string array item identified + by `{arrayIndex}`." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsSessionTicketsString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsSessionTicket + summary: "Delete a ticket array item in a listener" + description: "Deletes an item from the `tickets` string array." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/certificate: + summary: "Endpoint for the `listeners/{listenerName}/tls/certificate` + object" + + get: + operationId: listListenerTlsCertificates + summary: "Retrieve the certificate option in a listener" + description: "Retrieves the `certificate` option that lists [certificate + bundles](https://unit.nginx.org/configuration/#certificate-management) + used with the `{listenerName}` listener." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `certificate` option exists in the + configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerTlsCertificate" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsCertificateArray" + + example2: + $ref: "#/components/examples/configListenerTlsCertificateString" + + "404": + $ref: "#/components/responses/responseNotFound" + + post: + operationId: insertListenerTlsCertificate + summary: "Add a new certificate array item in a listener" + description: "Adds a new certificate bundle name to the end of the + `certificate` string array." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsCertificateString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + put: + operationId: updateListenerTlsCertificates + summary: "Create or overwrite the certificate option in a listener" + description: "Creates or overwrites the entire `certificate` option." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/stringOrStringArray" + + examples: + example1: + $ref: "#/components/examples/configListenerTlsCertificateArray" + + example2: + $ref: "#/components/examples/configListenerTlsCertificateString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsCertificates + summary: "Delete the certificate option in a listener" + description: "Deletes the `certificate` option." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/tls/certificate/{arrayIndex}: + summary: "Endpoint for the `listeners/{listenerName}/tls/certificate` + string array item" + + get: + operationId: getListenerTlsCertificate + summary: "Retrieve a certificate array item in a listener" + description: "Retrieves the `{arrayIndex}`th item from the `certificate` + string array." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + description: "OK; the certificate bundle at `{arrayIndex}` exists in + the configuration." + + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsCertificateString" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerTlsCertificate + summary: "Update a certificate array item in a listener" + description: "Overwrites a single `certificate` string array item + identified by `{arrayIndex}`." + + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerTlsCertificateString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerTlsCertificate + summary: "Delete a certificate array item in a listener" + description: "Deletes an item from the `certificate` string array." + tags: + - listeners + - config + - tls + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/forwarded: + summary: "Endpoint for the `listeners/{listenerName}/forwarded` object" + get: + operationId: getListenerForwarded + summary: "Retrieve the forwarded object in a listener" + description: "Retrieves the `forwarded` object that configures + [originating IP identification] + (https://unit.nginx.org/configuration/#ip-protocol-forwarding) + for the `{listenerName}` listener." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `forwarded` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerForwarded" + + examples: + example1: + $ref: "#/components/examples/configListenerForwarded" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerForwarded + summary: "Create or overwrite the forwarded object in a listener" + description: "Creates or overwrites the entire `forwarded` object." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configListenerForwarded" + + examples: + example1: + $ref: "#/components/examples/configListenerForwarded" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerForwared + summary: "Delete the forwarded object in a listener" + description: "Deletes the `forwarded` object." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/forwarded/client_ip: + summary: "Endpoint for the `listeners/{listenerName}/forwarded/client_ip` + option" + + get: + operationId: getListenerForwardedClientIp + summary: "Retrieve the client_ip option in a listener" + description: "Retrieves the `client_ip` option that configures the headers + expected by the `{listenerName}` listener for + [originating IP identification] + (https://unit.nginx.org/configuration/#originating-ip-identification)." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `client_ip` option exists in the configuration." + + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedClientIp" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerForwardedClientIp + summary: "Create or overwrite the client_ip option in a listener" + description: "Creates or overwrites the `client_ip` option." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedClientIp" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + /config/listeners/{listenerName}/forwarded/protocol: + summary: "Endpoint for the `listeners/{listenerName}/forwarded/protocol` + option" + + get: + operationId: getListenerForwardedProtocol + summary: "Retrieve the protocol option in a listener" + description: "Retrieves the `protocol` option that configures the protocol + expected by the `{listenerName}` listener for + [originating IP identification] + (https://unit.nginx.org/configuration/#originating-ip-identification)." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `protocol` option exists in the configuration." + + content: + application/json: + schema: + type: string + enum: + - "http" + - "https" + - "on" + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedProtocol" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerForwardedProtocol + summary: "Create or overwrite the protocol option in a listener" + description: "Creates or overwrites the `protocol` option." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + enum: + - "http" + - "https" + - "on" + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedProtocol" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + /config/listeners/{listenerName}/forwarded/recursive: + summary: "Endpoint for the `listeners/{listenerName}/forwarded/recursive` + option" + + get: + operationId: getListenerForwardedRecursive + summary: "Retrieve the recursive option in a listener" + description: "Retrieves the `recursive` option that controls how the + `{listenerName}` listener uses [originating IP identification] + (https://unit.nginx.org/configuration/#originating-ip-identification)." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `recursive` option exists in the configuration." + + content: + application/json: + schema: + type: boolean + + examples: + example1: + summary: "Enables recursive header field traversal" + value: true + + example2: + summary: "Disables recursive header field traversal" + value: false + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerForwardedRecursive + summary: "Create or overwrite the recursive option in a listener" + description: "Creates or overwrites the `recursive` option." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: boolean + + examples: + example1: + summary: "Enables recursive header field traversal" + value: true + + example2: + summary: "Disables recursive header field traversal" + value: false + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerForwardedRecursive + summary: "Delete the recursive object in a listener" + description: "Deletes the `recursive` object." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/forwarded/source: + summary: "Endpoint for the `listeners/{listenerName}/forwarded/source` + object" + + get: + operationId: listListenerForwardedSources + summary: "Retrieve the source option in a listener" + description: "Retrieves the `source` option that defines address patterns + for trusted addresses, used by the `{listenerName}` listener for + [originating IP identification] + (https://unit.nginx.org/configuration/#originating-ip-identification)." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `source` option exists in the configuration." + content: + application/json: + schema: + $ref: "#/components/schemas/stringOrStringArray" + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedSourceArray" + + example2: + $ref: "#/components/examples/configListenerForwardedSourceString" + + "404": + $ref: "#/components/responses/responseNotFound" + + post: + operationId: insertListenerForwardedSource + summary: "Add a new source array item in a listener" + description: "Adds a new source bundle name to the end of the `source` + string array defines address patterns for trusted addresses, used by + the `{listenerName}` listener for [originating IP identification] + (https://unit.nginx.org/configuration/#originating-ip-identification)." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedSourceString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + put: + operationId: updateListenerForwardedSources + summary: "Create or overwrite the source option in a listener" + description: "Creates or overwrites the entire `source` option." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/stringOrStringArray" + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedSourceArray" + + example2: + $ref: "#/components/examples/configListenerForwardedSourceString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerForwardedSources + summary: "Delete the source option in a listener" + description: "Deletes the `source` option." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/listeners/{listenerName}/forwarded/source/{arrayIndex}: + summary: "Endpoint for the `listeners/{listenerName}/forwarded/source` + string array item" + + get: + operationId: getListenerForwardedSource + summary: "Retrieve a source array item in a listener" + description: "Retrieves the `{arrayIndex}`th item from the `source` + string array." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + description: "OK; the address pattern at `{arrayIndex}` exists in the + configuration." + + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedSourceString" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerForwardedSource + summary: "Update a source array item in a listener" + description: "Overwrites a single `source` string array item identified + by `{arrayIndex}`." + + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + requestBody: + required: true + content: + application/json: + schema: + type: string + + examples: + example1: + $ref: "#/components/examples/configListenerForwardedSourceString" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteListenerForwardedSource + summary: "Delete a source array item in a listener" + description: "Deletes an item from the `source` string array." + tags: + - listeners + - config + - xff + + parameters: + - $ref: "#/components/parameters/listenerName" + - $ref: "#/components/parameters/arrayIndex" + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/routes: + summary: "Endpoint for the `routes` entity in the configuration" + get: + operationId: getRoutes + summary: "Retrieve the routes entity" + description: "Retrieves the `routes` entity that represents Unit's + [routes](https://unit.nginx.org/configuration/#routes)." + + tags: + - config + - routes + + responses: + "200": + description: "OK; the `routes` entity exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configRoutes" + + examples: + example1: + $ref: "#/components/examples/configRoutes" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateRoutes + summary: "Overwrite the routes entity" + description: "Overwrites the `routes` entity in the configuration." + tags: + - config + - routes + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configRoutes" + + examples: + example1: + $ref: "#/components/examples/configRoutes" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteRoutes + summary: "Delete the routes entity" + description: "Deletes the `routes` entity from the configuration." + tags: + - config + - routes + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings: + summary: "Endpoint for the `settings` object in the configuration" + get: + operationId: getSettings + summary: "Retrieve the settings object" + description: "Retrieves the `settings` object that represents Unit's + [global settings](https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `settings` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configSettings" + + examples: + example1: + $ref: "#/components/examples/configSettings" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettings + summary: "Create or overwrite the settings object" + description: "Creates or overwrites the `settings` object in the + configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configSettings" + + examples: + example1: + $ref: "#/components/examples/configSettings" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettings + summary: "Delete the settings object" + description: "Deletes the `settings` object from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http: + summary: "Endpoint for the `http` object in `settings`" + + get: + operationId: getSettingsHttp + summary: "Retrieve the http object from settings" + description: "Retrieves the `http` object that represents Unit's + [HTTP settings](https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `http` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttp" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttp" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttp + summary: "Create or overwrite the http object" + description: "Creates or overwrites the `http` object in the + configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttp" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttp" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttp + summary: "Delete the http object" + description: "Deletes the `http` object from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/body_read_timeout: + summary: "Endpoint for the `body_read_timeout` option in `http`" + get: + operationId: getSettingsHttpBodyReadTimeout + summary: "Retrieve the body_read_timeout option from http settings" + description: "Retrieves the `body_read_timeout` option that represents + Unit's [request body read timeout] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `body_read_timeout` option exists in the + configuration." + + content: + application/json: + schema: + type: integer + + examples: + BodyReadTimeout: + value: 30 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpBodyReadTimeout + summary: "Create or overwrite the body_read_timeout option" + description: "Creates or overwrites the `body_read_timeout` option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + BodyReadTimeout: + value: 30 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpBodyReadTimeout + summary: "Delete the body_read_timeout option" + description: "Deletes the `body_read_timeout` option from the + configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/discard_unsafe_fields: + summary: "Endpoint for the `discard_unsafe_fields` option in `http`" + get: + operationId: getSettingsDiscardUnsafeFields + summary: "Retrieve the discard_unsafe_fields option from http settings" + description: "Retrieves the `discard_unsafe_fields` option that represents + Unit's [header processing behavior] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `discard_unsafe_fields` option exists in + the configuration." + + content: + application/json: + schema: + type: boolean + + examples: + DiscardUnsafeFields: + value: true + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsDiscardUnsafeFields + summary: "Create or overwrite the discard_unsafe_fields option" + description: "Creates or overwrites the `discard_unsafe_fields` option + in the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: boolean + + examples: + DiscardUnsafeFields: + value: true + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsDiscardUnsafeFields + summary: "Delete the discard_unsafe_fields option" + description: "Deletes the `discard_unsafe_fields` option from + the configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/header_read_timeout: + summary: "Endpoint for the `header_read_timeout` option in `http`" + get: + operationId: getSettingsHttpHeaderReadTimeout + summary: "Retrieve the header_read_timeout option from http settings" + description: "Retrieves the `header_read_timeout` option that represents + Unit's [request headers read timeout] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `header_read_timeout` option exists in + the configuration." + + content: + application/json: + schema: + type: integer + + examples: + HeaderReadTimeout: + value: 30 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpHeaderReadTimeout + summary: "Create or overwrite the header_read_timeout option" + description: "Creates or overwrites the `header_read_timeout` option + in the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + HeaderReadTimeout: + value: 30 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpHeaderReadTimeout + summary: "Delete the header_read_timeout option" + description: "Deletes the `header_read_timeout` option from + the configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/idle_timeout: + summary: "Endpoint for the `idle_timeout` option in `http`" + get: + operationId: getSettingsHttpIdleTimeout + summary: "Retrieve the idle_timeout option from http settings" + description: "Retrieves the `idle_timeout` option that represents + Unit's [keep-alive idling timeout] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `idle_timeout` option exists in + the configuration." + + content: + application/json: + schema: + type: integer + + examples: + IdleTimeout: + value: 180 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpIdleTimeout + summary: "Create or overwrite the idle_timeout option" + description: "Creates or overwrites the `idle_timeout` option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + IdleTimeout: + value: 180 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpIdleTimeout + summary: "Delete the idle_timeout option" + description: "Deletes the `idle_timeout` option from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/log_route: + summary: "Endpoint for the `log_route` option in `http`" + get: + operationId: getSettingsLogRoute + summary: "Retrieve the log_route option from http settings" + description: "Retrieves the `log_route` option that controls + Unit's [router logging] + (https://unit.nginx.org/troubleshooting/#router-log)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `log_route` option exists in + the configuration." + + content: + application/json: + schema: + type: boolean + + examples: + LogRoute: + value: true + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsLogRoute + summary: "Create or overwrite the log_route option" + description: "Creates or overwrites the `log_route` option + in the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: boolean + + examples: + LogRoute: + value: true + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsLogRoute + summary: "Delete the log_route option" + description: "Deletes the `log_route` option from + the configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/max_body_size: + summary: "Endpoint for the `max_body_size` option in `http`" + get: + operationId: getSettingsHttpMaxBodySize + summary: "Retrieve the max_body_size option from http settings" + description: "Retrieves the `max_body_size` option that represents + Unit's [request body size limit] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `max_body_size` option exists in + the configuration." + + content: + application/json: + schema: + type: integer + + examples: + MaxBodySize: + value: 8388608 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpMaxBodySize + summary: "Create or overwrite the max_body_size option" + description: "Creates or overwrites the `max_body_size` option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + MaxBodySize: + value: 8388608 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpMaxBodySize + summary: "Delete the max_body_size option" + description: "Deletes the `max_body_size` option from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/send_timeout: + summary: "Endpoint for the `send_timeout` option in `http`" + get: + operationId: getSettingsHttpSendTimeout + summary: "Retrieve the send_timeout option from http settings" + description: "Retrieves the `send_timeout` option that represents + Unit's [response send timeout] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `send_timeout` option exists in + the configuration." + + content: + application/json: + schema: + type: integer + + examples: + SendTimeout: + value: 30 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpSendTimeout + summary: "Create or overwrite the send_timeout option" + description: "Creates or overwrites the `send_timeout` option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + SendTimeout: + value: 30 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpSendTimeout + summary: "Delete the send_timeout option" + description: "Deletes the `send_timeout` option from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/server_version: + summary: "Endpoint for the `server_version` option in `http`" + get: + operationId: getSettingsServerVersion + summary: "Retrieve the server_version option from http settings" + description: "Retrieves the `server_version` option that controls + Unit's [Server header field versioning] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `server_version` option exists in + the configuration." + + content: + application/json: + schema: + type: boolean + + examples: + ServerVersion: + value: true + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsServerVersion + summary: "Create or overwrite the server_version option" + description: "Creates or overwrites the `server_version` option + in the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: boolean + + examples: + ServerVersion: + value: true + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsServerVersion + summary: "Delete the server_version option" + description: "Deletes the `server_version` option from + the configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/static: + summary: "Endpoint for the `static` object in `http`" + get: + operationId: getSettingsHttpStatic + summary: "Retrieve the static object from http settings" + description: "Retrieves the `static` object that represents + Unit's [static content settings] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `static` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStatic" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStatic" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpStatic + summary: "Create or overwrite the static object" + description: "Creates or overwrites the `static` object in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStatic" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStatic" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpStatic + summary: "Delete the static object" + description: "Deletes the `static` object from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/static/mime_types: + summary: "Endpoint for the `mime_types` object in `static`" + get: + operationId: getSettingsHttpStaticMimeTypes + summary: "Retrieve the mime_types object from static settings" + description: "Retrieves the `mime_types` object that represents Unit's + [MIME type settings](https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `mime_types` object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStaticMimeTypes" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStaticMimeTypes" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpStaticMimeTypes + summary: "Create or overwrite the mime_types object" + description: "Creates or overwrites the `mime_types` object in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStaticMimeTypes" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStaticMimeTypes" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpStaticMimeTypes + summary: "Delete the mime_types object" + description: "Deletes the `mime_types` object from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /config/settings/http/static/mime_types/{mimeType}: + summary: "Endpoint for a MIME type option in `mime_types`" + parameters: + - $ref: "#/components/parameters/mimeType" + + get: + operationId: getSettingsHttpStaticMimeType + summary: "Retrieve the MIME type option from MIME type settings" + description: "Retrieves the MIME type option that represents a + [MIME type](https://unit.nginx.org/configuration/#settings) + supported by Unit." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the MIME type option exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStaticMimeType" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStaticMimeType" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsHttpStaticMimeType + summary: "Create or overwrite the MIME type option" + description: "Creates or overwrites the MIME type option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/configSettingsHttpStaticMimeType" + + examples: + example1: + $ref: "#/components/examples/configSettingsHttpStaticMimeType" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsHttpStaticMimeType + summary: "Delete the MIME type option" + description: "Deletes the MIME type option from the configuration." + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + + /status: + summary: "Endpoint for the `status` object" + get: + operationId: getStatus + summary: "Retrieve the status object" + description: "Retrieves the entire `/status` section that represents + Unit's [usage statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `status` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/status" + + examples: + example1: + $ref: "#/components/examples/status" + + /status/connections: + summary: "Endpoint for the `connections` status object" + get: + operationId: getStatusConnections + summary: "Retrieve the connections status object" + description: "Retrieves the `connections` status object that represents + Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `connections` object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusConnections" + + examples: + example1: + $ref: "#/components/examples/statusConnections" + + /status/connections/accepted: + summary: "Endpoint for the `accepted` connections number" + get: + operationId: getStatusConnectionsAccepted + summary: "Retrieve the accepted connections number" + description: "Retrieves the `accepted` connections number that represents + Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `active` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Accepted: + value: 1067 + + /status/connections/active: + summary: "Endpoint for the `active` connections number" + get: + operationId: getStatusConnectionsActive + summary: "Retrieve the active connections number" + description: "Retrieves the `active` connections number that represents + Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `active` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Active: + value: 13 + + /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 + + /status/connections/closed: + summary: "Endpoint for the `closed` connections number" + get: + operationId: getStatusConnectionsClosed + summary: "Retrieve the closed connections number" + description: "Retrieves the `closed` connections number that represents + Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `closed` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Closed: + value: 4 + + /status/requests: + summary: "Endpoint for the `requests` status object" + get: + operationId: getStatusRequests + summary: "Retrieve the requests status object" + description: "Retrieves the `requests` status object that represents + Unit's instance [request statistics] + (https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `requests` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusRequests" + + examples: + example1: + $ref: "#/components/examples/statusRequests" + + /status/requests/total: + summary: "Endpoint for the `total` requests number" + get: + operationId: getStatusRequestsTotal + summary: "Retrieve the total requests number" + description: "Retrieves the `total` requests number that represents Unit's + instance [request statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + responses: + "200": + description: "OK; the `total` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Closed: + value: 1307 + + /status/applications: + summary: "Endpoint for the `applications` status object" + get: + operationId: getStatusApplications + summary: "Retrieve the applications status object" + description: "Retrieves the `applications` status object that represents + Unit's per-app + [process and request statistics](https://unit.nginx.org/usagestats/)." + tags: + - status + + responses: + "200": + description: "OK; the `applications` object exists in + the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusApplications" + + examples: + example1: + $ref: "#/components/examples/statusApplications" + + /status/applications/{appName}: + summary: "Endpoint for the app status object" + get: + operationId: getStatusApplicationsApp + summary: "Retrieve the app status object" + description: "Retrieves the app status object that represents + Unit's per-app + [process and request statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the app object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusApplicationsApp" + + examples: + example1: + $ref: "#/components/examples/statusApplicationsApp" + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/applications/{appName}/processes: + summary: "Endpoint for the `processes` app status object" + get: + operationId: getStatusApplicationsAppProcesses + summary: "Retrieve the processes app status object" + description: "Retrieves the `processes` app status object that represents + Unit's per-app + [process statistics](https://unit.nginx.org/usagestats/)." + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `processes` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusApplicationsAppProcesses" + + examples: + example1: + $ref: "#/components/examples/statusApplicationsAppProcesses" + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/applications/{appName}/processes/running: + summary: "Endpoint for the `running` processes number" + get: + operationId: getStatusApplicationsAppProcessesRunning + summary: "Retrieve the running processes app status number" + description: "Retrieves the `running` processes number that represents + Unit's per-app + [process statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `running` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Running: + value: 9 + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/applications/{appName}/processes/starting: + summary: "Endpoint for the `starting` processes number" + get: + operationId: getStatusApplicationsAppProcessesStarting + summary: "Retrieve the starting processes app status number" + description: "Retrieves the `starting` processes number that represents + Unit's per-app + [process statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `starting` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Starting: + value: 1 + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/applications/{appName}/processes/idle: + summary: "Endpoint for the `idle` processes number" + get: + operationId: getStatusApplicationsAppProcessesIdle + summary: "Retrieve the idle processes app status number" + description: "Retrieves the `idle` processes number that represents + Unit's per-app + [process statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `idle` number exists in the configuration." + content: + application/json: + schema: + type: integer + + examples: + Idle: + value: 0 + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/applications/{appName}/requests: + summary: "Endpoint for the `requests` app status object" + get: + operationId: getStatusApplicationsAppRequests + summary: "Retrieve the requests app status object" + description: "Retrieves the `requests` app status object that represents + Unit's per-app + [request statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `requests` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusApplicationsAppRequests" + + examples: + example1: + $ref: "#/components/examples/statusApplicationsAppRequests" + + /status/applications/{appName}/requests/active: + summary: "Endpoint for the `active` requests number" + get: + operationId: getStatusApplicationsAppRequestsActive + summary: "Retrieve the active requests app status number" + description: "Retrieves the `active` requests number that represents + Unit's per-app + [request statistics](https://unit.nginx.org/usagestats/)." + + tags: + - status + + parameters: + - $ref: "#/components/parameters/appName" + + responses: + "200": + description: "OK; the `active` number exists in the configuration." + + content: + application/json: + schema: + type: integer + + examples: + Idle: + value: 15 + + "404": + $ref: "#/components/responses/responseNotFound" + +components: + # -- PARAMETERS -- + + parameters: + appName: + in: path + description: "An application's name in the configuration." + name: appName + required: true + schema: + type: string + + arrayIndex: + in: path + description: "A zero-based index in a configuration array." + name: arrayIndex + required: true + schema: + type: integer + + arrayIndex2: + in: path + description: "A zero-based index in a configuration array." + name: arrayIndex2 + required: true + schema: + type: integer + + bundleName: + in: path + description: "A certificate bundle's name" + name: bundleName + required: true + schema: + type: string + + listenerName: + in: path + description: "Listener name; a unique combination of a host IP address + (or a `*` wildcard to match any host IP addresses), followed by a colon + and a port number, such as `127.0.0.1:80` or `*:443`." + + name: listenerName + required: true + schema: + type: string + + mimeType: + in: path + description: "A MIME type name, such as `text/x-code` or + `application/json`." + name: mimeType + required: true + schema: + type: string + + # -- EXAMPLES -- + + examples: + # -- RESPONSE EXAMPLES -- + + errorInvalidJson: + summary: "400 error response" + value: + error: "Invalid JSON." + detail: 'A valid JSON value is expected here. It must be either a + literal (null, true, or false), a number, a string (in double quotes + ""), an array (with brackets []), or an object (with braces {}).' + + location: + offset: 0 + line: 1 + column: 0 + + errorValueDoesntExist: + summary: "404 error response" + value: + error: "Value doesn't exist." + + errorInternalError: + summary: "500 error response" + value: + error: "Failed to apply new configuration." + + successReconfigurationDone: + summary: "Success response" + value: + success: "Reconfiguration done." + + # -- CONFIGURATION EXAMPLES -- + + # /certificates + cert: + summary: "Certificate bundle or bundles" + value: + bundle: + key: "RSA (4096 bits)" + chain: + - subject: + common_name: "example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + alt_names: + - "example.com" + - "www.example.com" + + issuer: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + + validity: + since: "Feb 22 22:45:55 2023 GMT" + until: "Feb 21 22:45:55 2016 GMT" + + - subject: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + issuer: + common_name: "root.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + validity: + since: "Sep 18 19:46:19 2022 GMT" + until: "Jun 15 19:46:19 2025 GMT" + + # /certificates/{bundleName} + certBundle: + summary: "Single certificate bundle" + value: + key: "RSA (4096 bits)" + chain: + - subject: + common_name: "example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + alt_names: + - "example.com" + - "www.example.com" + + issuer: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + + validity: + since: "Feb 22 22:45:55 2023 GMT" + until: "Feb 21 22:45:55 2016 GMT" + + - subject: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + issuer: + common_name: "root.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + validity: + since: "Sep 18 19:46:19 2022 GMT" + until: "Jun 15 19:46:19 2025 GMT" + + # /certificates/{bundleName}/chain + certBundleChain: + summary: "Certificate chain" + value: + - subject: + common_name: "example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + alt_names: + - "example.com" + - "www.example.com" + + issuer: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + + validity: + since: "Feb 22 22:45:55 2023 GMT" + until: "Feb 21 22:45:55 2016 GMT" + + - subject: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + issuer: + common_name: "root.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme Certification Authority" + + validity: + since: "Sep 18 19:46:19 2022 GMT" + until: "Jun 15 19:46:19 2025 GMT" + + # /certificates/{bundleName}/chain/{arrayIndex} + certBundleChainCert: + summary: "Single certificate" + value: + subject: + common_name: "example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + alt_names: + - "example.com" + - "www.example.com" + + issuer: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + + validity: + since: "Feb 22 22:45:55 2023 GMT" + until: "Feb 21 22:45:55 2016 GMT" + + # /certificates/{bundleName}/chain/{arrayIndex}/issuer + certBundleChainCertIssuer: + summary: "Certificate's issuer" + value: + common_name: "intermediate.ca.example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + + # /certificates/{bundleName}/chain/{arrayIndex}/subject + certBundleChainCertSubj: + summary: "Certificate's subject" + value: + common_name: "example.com" + country: "US" + state_or_province: "CA" + organization: "Acme, Inc." + alt_names: + - "example.com" + - "www.example.com" + + # /certificates/{bundleName}/chain/{arrayIndex}/validity + certBundleChainCertValidity: + summary: "Certificate's validity" + value: + since: "Feb 22 22:45:55 2023 GMT" + until: "Feb 21 22:45:55 2016 GMT" + + # /config + config: + summary: "The entire /config section of the API" + value: + access_log: "/var/log/unit/access.log" + + applications: + nodejsapp: + type: "external" + working_directory: "/www/app/node-app/" + executable: "app.js" + user: "www" + group: "www" + arguments: + - "--tmp-files" + - "/tmp/node-cache" + + pythonapp: + type: "python 3.11" + processes: 16 + working_directory: "/www/app/python-app/" + path: "blog" + module: "blog.wsgi" + user: "www" + group: "www" + stderr: "stderr.log" + isolation: + rootfs: "/www/" + + routes: + local: + - action: + share: "/www/local/" + + global: + - match: + host: "backend.example.com" + + action: + pass: "applications/pythonapp" + + - action: + pass: "applications/nodejsapp" + + listeners: + 127.0.0.1:8080: + pass: "routes/local" + + "*:443": + pass: "routes/global" + tls: + certificate: "bundle" + conf_commands: + ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + minprotocol: "TLSv1.3" + + session: + cache_size: 10240 + timeout: 60 + tickets: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + + forwarded: + client_ip: "X-Forwarded-For" + recursive: false + source: + - "192.0.2.0/24" + - "198.51.100.0/24" + + settings: + http: + body_read_timeout: 30 + discard_unsafe_fields: true + header_read_timeout: 30 + idle_timeout: 180 + log_route: true + max_body_size: 8388608 + send_timeout: 30 + server_version: false + + # /config/access_log + configAccessLogBasic: + summary: "Basic access_log string" + value: "/var/log/unit/access.log" + + # /config/access_log + configAccessLogComplex: + summary: "Complex access_log object" + value: + path: "/var/log/unit/access.log" + format: '$remote_addr - - [$time_local] "$request_line" $status + $body_bytes_sent "$header_referer" "$header_user_agent"' + + # /config/applications/{appName} + configApplication: + summary: "Individual Unit application" + value: + type: "python 3.11" + processes: 16 + working_directory: "/www/app/python-app/" + path: "blog" + module: "blog.wsgi" + user: "www" + group: "www" + stderr: "stderr.log" + stdout: "stdout.log" + isolation: + rootfs: "/www/" + + # /config/applications + configApplications: + summary: "Entire Unit applications section" + value: + nodejsapp: + type: "external" + working_directory: "/www/app/node-app/" + executable: "app.js" + user: "www" + group: "www" + arguments: + - "--tmp-files" + - "/tmp/node-cache" + + pythonapp: + type: "python 3.11" + processes: 16 + working_directory: "/www/app/python-app/" + path: "blog" + module: "blog.wsgi" + user: "www" + group: "www" + stderr: "stderr.log" + isolation: + rootfs: "/www/" + + # /config/listeners + configListeners: + summary: "Multiple listeners" + value: + 127.0.0.1:8080: + pass: "applications/wp_emea_dev" + "*:443": + pass: "applications/php_app/target" + tls: + certificate: "bundle" + conf_commands: + ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + minprotocol: "TLSv1.3" + session: + cache_size: 10240 + timeout: 60 + tickets: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + forwarded: + client_ip: "X-Forwarded-For" + recursive: false + source: + - "192.0.2.0/24" + - "198.51.100.0/24" + + # /config/listeners/{listenerName} + configListenerSimple: + summary: "Simple listener object" + value: + pass: "applications/wp_emea_dev" + + # /config/listeners/{listenerName} + configListenerComplex: + summary: "Elaborate listener object" + value: + pass: "applications/php_app/target" + tls: + certificate: "bundle" + conf_commands: + ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + minprotocol: "TLSv1.3" + session: + cache_size: 10240 + timeout: 60 + tickets: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + forwarded: + client_ip: "X-Forwarded-For" + recursive: false + protocol: "http" + source: + - "192.0.2.0/24" + - "198.51.100.0/24" + + # /config/listeners/{listenerName}/forwarded + configListenerForwarded: + summary: "Originating IP identification configuration object" + value: + client_ip: "X-Forwarded-For" + recursive: false + source: + - "192.0.2.0/24" + - "198.51.100.0/24" + + # /config/listeners/{listenerName}/forwarded/source + configListenerForwardedSourceArray: + summary: "Array of source address patterns" + value: + - "192.0.2.0/24" + - "198.51.100.0/24" + + # /config/listeners/{listenerName}/forwarded/source + configListenerForwardedSourceString: + summary: "Single source address pattern" + value: "192.0.2.0/24" + + # /config/listeners/{listenerName}/forwarded/client_ip + configListenerForwardedClientIp: + summary: "Client IP headers expected by a listener" + value: "X-Forwarded-For" + + # /config/listeners/{listenerName}/forwarded/protocol + configListenerForwardedProtocol: + summary: "Protocol header expected by a listener" + value: "http" + + # /config/listeners/{listenerName}/pass + configListenerPassApp: + summary: "Application destination in a listener" + value: "applications/wp_emea_dev" + + # /config/listeners/{listenerName}/pass + configListenerPassRoute: + summary: "Route destination in a listener" + value: "routes/staticsite" + + # /config/listeners/{listenerName}/pass + configListenerPassAppTarget: + summary: "App target destination in a listener" + value: "applications/php_app/index_target" + + # /config/listeners/{listenerName}/tls + configListenerTls: + summary: "TLS object in a listener" + value: + certificate: "bundle" + conf_commands: + ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + minprotocol: "TLSv1.3" + session: + cache_size: 10240 + timeout: 60 + tickets: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + + # /config/listeners/{listenerName}/tls/certificate + configListenerTlsCertificateArray: + summary: "Array of certificate bundle names" + value: + - bundle_old + - bundle_new + + # /config/listeners/{listenerName}/tls/certificate + configListenerTlsCertificateString: + summary: "Single certificate bundle name" + value: bundle + + # /config/listeners/{listenerName}/tls/conf_commands + configListenerTlsConfCommands: + summary: "TLS configuration commands in an object" + value: + ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + minprotocol: "TLSv1.3" + + # /config/listeners/{listenerName}/tls/session + configListenerTlsSession: + summary: "Session settings object" + value: + cache_size: 10240 + timeout: 60 + tickets: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + + # /config/listeners/{listenerName}/tls/session/tickets + configListenerTlsSessionTicketsBool: + summary: "Boolean value that enables or disables random tickets" + value: true + + # /config/listeners/{listenerName}/tls/session/tickets + configListenerTlsSessionTicketsString: + summary: "Single session ticket key" + value: "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + + # /config/listeners/{listenerName}/tls/session/tickets + configListenerTlsSessionTicketsArray: + summary: "Multiple session ticket keys" + value: + - "IAMkP16P8OBuqsijSDGKTpmxrzfFNPP4EdRovXH2mqstXsodPC6MqIce5NlMzHLP" + - "Ax4bv/JvMWoQG+BfH0feeM9Qb32wSaVVKOj1+1hmyU8ORMPHnf3Tio8gLkqm2ifC" + + # /config/routes + configRoutes: + summary: "Routes array" + value: + - action: + pass: "applications/${host}_php_handler" + + match: + arguments: + mode: "strict" + fullAccess: "true" + + uri: "~^/data/www/.*\\.php(/.*)?$" + + - action: + share: "/www/data$uri" + + match: + headers: + - User-Agent: "curl*" + + source: + - "!192.168.1.1" + - "!10.1.1.0/16" + - "192.168.1.0/24" + - "2001:0db8::/32" + + - action: + return: 301 + location: "https://www.example.com" + + # /config/settings + configSettings: + summary: "Global settings" + value: + http: + body_read_timeout: 30 + discard_unsafe_fields: true + header_read_timeout: 30 + idle_timeout: 180 + log_route: true + max_body_size: 8388608 + send_timeout: 30 + server_version: false + static: + mime_types: + "text/x-code": + - ".c" + - ".h" + + # /config/settings/http + configSettingsHttp: + summary: "HTTP settings" + value: + body_read_timeout: 30 + discard_unsafe_fields: true + header_read_timeout: 30 + idle_timeout: 180 + log_route: true + max_body_size: 8388608 + send_timeout: 30 + server_version: false + static: + mime_types: + "text/x-code": + - ".c" + - ".h" + + # /config/settings/http/static + configSettingsHttpStatic: + summary: "Static content settings" + value: + mime_types: + "text/x-code": + - ".c" + - ".h" + + # /config/settings/http/static/mime_types/{optionName} + configSettingsHttpStaticMimeType: + summary: "Individual MIME type" + value: + - ".c" + - ".h" + + # /config/settings/http/static/mime_types + configSettingsHttpStaticMimeTypes: + summary: "MIME types recognized by Unit" + value: + "text/x-code": + - ".c" + - ".h" + + # /status + status: + summary: "Regular status object" + value: + connections: + accepted: 1067 + active: 13 + idle: 4 + closed: 1050 + requests: + total: 1307 + applications: + wp: + processes: + running: 9 + starting: 1 + idle: 0 + requests: + active: 15 + + # /status/connections + statusConnections: + summary: "Regular connections status object" + value: + accepted: 1067 + active: 13 + idle: 4 + closed: 1050 + + # /status/applications + statusApplications: + summary: "Regular applications status object" + value: + wp: + processes: + running: 9 + starting: 1 + idle: 0 + requests: + active: 15 + + # /status/applications/{appName} + statusApplicationsApp: + summary: "Regular app status object" + value: + processes: + running: 9 + starting: 1 + idle: 0 + requests: + active: 15 + + # /status/applications/{appName}/processes + statusApplicationsAppProcesses: + summary: "Regular app processes status object" + value: + running: 9 + starting: 1 + idle: 0 + + # /status/applications/{appName}/requests + statusApplicationsAppRequests: + summary: "Regular app requests status object" + value: + active: 15 + + # /status/requests + statusRequests: + summary: "Regular requests status object" + value: + total: 1307 + + # -- RESPONSES -- + + responses: + responseOkDeleted: + description: "OK; the value was deleted." + content: + application/json: + schema: + $ref: "#/components/schemas/jsonSuccessMessage" + + examples: + example1: + $ref: "#/components/examples/successReconfigurationDone" + + responseOkUpdated: + description: "OK; the value was updated." + content: + application/json: + schema: + $ref: "#/components/schemas/jsonSuccessMessage" + + examples: + example1: + $ref: "#/components/examples/successReconfigurationDone" + + responseBadRequest: + description: "Bad Request; invalid JSON payload was provided. + This may occur if the payload supplied doesn't match the JSON schema for + the respective configuration section." + + content: + application/json: + schema: + $ref: "#/components/schemas/jsonErrorMessage" + + examples: + example1: + $ref: "#/components/examples/errorInvalidJson" + + responseNotFound: + description: "Not Found; the value does not exist in the configuration. + This may occur if any part of the path is non-existent." + + content: + application/json: + schema: + $ref: "#/components/schemas/jsonErrorMessage" + + examples: + example1: + $ref: "#/components/examples/errorValueDoesntExist" + + responseInternalError: + description: "Internal server error; the configuration wasn't applied. + This may occur with misconfigured paths, wrong permissions, etc." + + content: + application/json: + schema: + $ref: "#/components/schemas/jsonErrorMessage" + + examples: + example1: + $ref: "#/components/examples/errorInternalError" + + # -- SCHEMAS -- + + schemas: + # -- GENERIC REUSABLE OBJECTS -- + + stringArray: + type: array + description: "An array of strings." + items: + type: string + + stringOrStringArray: + description: "A string or an array of strings." + oneOf: + - type: string + - $ref: "#/components/schemas/stringArray" + + jsonSuccessMessage: + type: object + description: "JSON message on success." + additionalProperties: + type: string + + jsonErrorMessage: + type: object + description: "JSON message on error." + additionalProperties: + type: string + + # Configuration sections as data types; hugely reliant on each other + + # /certificates + cert: + type: object + description: "An object whose options represent certificate bundles." + additionalProperties: + $ref: "#/components/schemas/certBundle" + + # /certificates/{bundleName} + certBundle: + type: object + description: "An object whose options represent a certificate bundle." + properties: + key: + type: string + description: "Certificate bundle's key type, i. e. RSA, ECDSA, etc." + + chain: + $ref: "#/components/schemas/certBundleChain" + + # /certificates/{bundleName}/chain + certBundleChain: + type: array + description: "An array whose items represent certificates in a bundle." + items: + $ref: "#/components/schemas/certBundleChainCert" + + # /certificates/{bundleName}/chain/{certIndex} + certBundleChainCert: + type: object + description: "An object that represents an individual certificate." + properties: + subject: + $ref: "#/components/schemas/certBundleChainCertSubj" + + issuer: + $ref: "#/components/schemas/certBundleChainCertIssuer" + + validity: + $ref: "#/components/schemas/certBundleChainCertValidity" + + # /certificates/{bundleName}/chain/{certIndex}/subject + certBundleChainCertSubj: + type: object + description: "An object that represents a certificate's subject." + properties: + common_name: + type: string + + country: + type: string + + state_or_province: + type: string + + organization: + type: string + + alt_names: + $ref: "#/components/schemas/stringArray" + + # /certificates/{bundleName}/chain/{certIndex}/issuer + certBundleChainCertIssuer: + type: object + description: "An object that represents a certificate's issuer." + properties: + common_name: + type: string + + country: + type: string + + state_or_province: + type: string + + organization: + type: string + + # /certificates/{bundleName}/chain/{certIndex}/validity + certBundleChainCertValidity: + type: object + description: "An object that represents the validity of a certificate." + properties: + since: + type: string + + until: + type: string + + # /config + config: + type: object + description: "The entire /config section of the API." + properties: + access_log: + $ref: "#/components/schemas/configAccessLog" + + applications: + $ref: "#/components/schemas/configApplications" + + routes: + $ref: "#/components/schemas/configRoutes" + + listeners: + $ref: "#/components/schemas/configListeners" + + settings: + $ref: "#/components/schemas/configSettings" + + # /config/access_log + configAccessLog: + description: "Configures the access log." + anyOf: + - type: string + - $ref: "#/components/schemas/configAccessLogObject" + + # /config/access_log + configAccessLogObject: + description: "Configures the access log." + type: object + properties: + format: + type: string + description: "Sets the log format. Besides arbitrary text, can contain + any variables Unit supports." + + default: '$remote_addr - - [$time_local] "$request_line" $status + $body_bytes_sent "$header_referer" "$header_user_agent"' + + path: + type: string + description: "Pathname of the access log file." + + # /config/applications + configApplications: + type: object + description: "An object whose options define individual applications." + additionalProperties: + $ref: "#/components/schemas/configApplication" + + # /config/applications/{appName} + configApplication: + type: object + description: "An object that defines an individual application." + anyOf: + - $ref: "#/components/schemas/configApplicationExternal" + - $ref: "#/components/schemas/configApplicationJava" + - $ref: "#/components/schemas/configApplicationPerl" + - $ref: "#/components/schemas/configApplicationPHP" + - $ref: "#/components/schemas/configApplicationPython" + - $ref: "#/components/schemas/configApplicationRuby" + + discriminator: + propertyName: type + mapping: + external: "#/components/schemas/configApplicationExternal" + java: "#/components/schemas/configApplicationJava" + perl: "#/components/schemas/configApplicationPerl" + php: "#/components/schemas/configApplicationPHP" + python: "#/components/schemas/configApplicationPython" + ruby: "#/components/schemas/configApplicationRuby" + + # ABSTRACT BASE SCHEMA, NOT PRESENT IN THE CONFIGURATION; STORES COMMON OPTIONS + configApplicationCommon: + type: object + description: "Common application object options." + required: + - type + + properties: + type: + type: string + description: "Application type and language version." + enum: [external, java, perl, php, python, ruby] + + environment: + type: object + description: "Environment variables to be passed to the app." + additionalProperties: + type: string + + group: + type: string + description: "Group name that runs the app process." + + isolation: + type: object + description: "Manages the isolation of an application process." + properties: + automount: + type: object + description: "Controls mount behavior if rootfs is enabled." + properties: + language_deps: + type: boolean + description: "Controls whether the language runtime + dependencies are automounted." + + default: true + + procfs: + type: boolean + description: "Controls whether the procfs is automounted." + default: true + + tmpfs: + type: boolean + description: "Controls whether the tmpfs is automounted." + default: true + + cgroup: + type: object + description: "Defines the app’s cgroup." + required: + - path + + properties: + path: + type: string + description: "Configures absolute or relative path of the app + in the cgroups v2 hierarchy." + + gidmap: + type: array + description: "Array of group ID mapping objects." + items: + type: object + description: "Group ID mapping object." + required: + - container + - host + - size + + properties: + container: + type: integer + description: "Starts the group ID mapping range in the + app’s namespace." + + host: + type: integer + description: "Starts the group ID mapping range in the + OS namespace." + + size: + type: integer + description: "Size of the ID range in both namespaces." + + namespaces: + type: object + properties: + cgroup: + type: boolean + description: "Creates a new cgroup namespace for the app." + default: false + + credential: + type: boolean + description: "Creates a new user namespace for the app." + default: false + + mount: + type: boolean + description: "Creates a new mount namespace for the app." + default: false + + network: + type: boolean + description: "Creates a new network namespace for the app." + default: false + + pid: + type: boolean + description: "Creates a new PID namespace for the app." + default: false + + uname: + type: boolean + description: "Creates a new UTS namespace for the app." + default: false + + rootfs: + type: string + description: "pathname of the directory to be used as the new + file system root for the app." + + uidmap: + type: array + description: "Array of user ID mapping objects." + items: + type: object + description: "User ID mapping object." + required: + - container + - host + - size + + properties: + container: + type: integer + description: "Starts the user ID mapping range in the + app’s namespace." + + host: + type: integer + description: "Starts the user ID mapping range in the + OS namespace." + + size: + type: integer + description: "Size of the ID range in both namespaces." + + limits: + type: object + description: "Governs the life cycle of an application process." + properties: + requests: + type: integer + description: "Maximum number of requests an app process + can serve." + + timeout: + type: integer + description: "Request timeout in seconds." + + processes: + description: "Governs the behavior of app processes." + anyOf: + - type: integer + - type: object + properties: + idle_timeout: + type: integer + description: "Number of seconds Unit waits for before + terminating an idle process that exceeds `spare`." + + max: + type: integer + description: "Maximum number of application processes that + Unit maintains (busy and idle)." + + default: 1 + + idle: + type: integer + description: "Minimum number of idle processes that Unit tries + to maintain for an app." + + default: 1 + + user: + type: string + description: "Username that runs the app process." + + stderr: + type: string + description: "Filename where Unit redirects the app's stderr stream." + + stdout: + type: string + description: "Filename where Unit redirects the app's stdout stream." + + working_directory: + type: string + description: "The app’s working directory." + + configApplicationExternal: + description: "Go or Node.js application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - executable + + properties: + executable: + type: string + description: "Pathname of the app, absolute or relative + to `working_directory`." + + arguments: + description: "Command-line arguments to be passed to the app." + $ref: "#/components/schemas/stringArray" + + configApplicationJava: + description: "Java application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - webapp + + properties: + webapp: + type: string + description: "Pathname of the application’s .war file + (packaged or unpackaged)." + + classpath: + description: "Paths to your app’s required libraries + (may point to directories or individual .jar files)." + + $ref: "#/components/schemas/stringArray" + + options: + desription: "JVM runtime options." + $ref: "#/components/schemas/stringArray" + + thread_stack_size: + type: integer + description: "Stack size of a worker thread in bytes." + + threads: + type: integer + description: "Number of worker threads per app process." + default: 1 + + configApplicationPerl: + description: "Perl application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - script + + properties: + script: + type: string + description: "PSGI script path." + + thread_stack_size: + type: integer + description: "Stack size of a worker thread in bytes." + + threads: + type: integer + description: "Number of worker threads per app process." + default: 1 + + configApplicationPHP: + description: "PHP application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - root + + properties: + root: + type: string + description: "Base directory of the app’s file structure." + + index: + type: string + description: "Filename added to URI paths that point to + directories if no `script` is set." + + default: "index.php" + + options: + type: object + description: "Defines the php.ini location and options." + properties: + admin: + type: object + description: "Extra directives set in PHP_INI_SYSTEM mode." + + additionalProperties: + type: string + + file: + type: string + description: "Pathname of the php.ini file." + + user: + type: object + description: "Extra directives set in PHP_INI_USER mode." + additionalProperties: + type: string + + script: + type: string + description: "Filename of a `root`-based PHP script that serves + all requests to the app." + + targets: + type: object + description: "Application sections with custom `root`, `script`, + and `index` values." + + additionalProperties: + type: object + required: + - root + + properties: + root: + type: string + description: "Base directory of the target’s + file structure." + + index: + type: string + description: "Filename added to URI paths that point to + directories if no `script` is set." + + default: "index.php" + + script: + type: string + description: "Filename of a `root`-based PHP script that + serves all requests to the target." + + configApplicationPython: + description: "Python application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - module + + properties: + module: + type: string + description: "App’s module name." + + callable: + type: string + description: "Name of the `module`-based callable that Unit runs + as the app." + + default: "application" + + home: + type: string + description: "Path to the app’s virtual environment, absolute or + relative to `working_directory`." + + path: + description: "Additional Python module lookup paths." + anyOf: + - type: string + - $ref: "#/components/schemas/stringArray" + + prefix: + type: string + description: "SCRIPT_NAME context value for WSGI or the + root_path context value for ASGI." + + protocol: + description: "Hints Unit that the app uses a certain interface." + enum: + - "asgi" + - "wsgi" + + targets: + type: object + description: "App sections with custom `module` and + `callable` values." + + additionalProperties: + type: object + required: + - module + + properties: + module: + type: string + description: "Target's module name." + + callable: + type: string + description: "Name of the `module`-based callable that Unit + runs as the target." + + default: "application" + + prefix: + type: string + description: "SCRIPT_NAME context value for WSGI or the + root_path context value for ASGI." + + thread_stack_size: + type: integer + description: "Stack size of a worker thread in bytes." + + threads: + type: integer + description: "Number of worker threads per app process." + default: 1 + + configApplicationRuby: + description: "Ruby application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - script + + properties: + script: + type: string + description: "Rack script pathname, including the .ru extension." + + hooks: + type: string + description: "Pathname of the .rb file setting the event hooks + invoked during the app’s lifecycle." + + threads: + type: integer + description: "Number of worker threads per app process." + default: 1 + + #/config/routes + configRoutes: + description: "Configures the routes." + anyOf: + - $ref: "#/components/schemas/configRouteArray" + - $ref: "#/components/schemas/configRoutesObject" + + #/config/routes/{routeName} or /config/routes + configRouteArray: + type: array + description: "An array whose items define individual route steps." + items: + $ref: "#/components/schemas/configRouteStep" + + #/config/routes + configRoutesObject: + type: object + description: "An object whose options define individual routes." + additionalProperties: + description: "Individual route arrays." + $ref: "#/components/schemas/configRouteArray" + + #/config/routes/{stepIndex} + #/config/routes/{routeName}/{stepIndex} + configRouteStep: + type: object + description: "An object whose options define a step's + conditions and action." + + required: + - action + + properties: + action: + description: "Defines how matching requests are handled." + $ref: "#/components/schemas/configRouteStepAction" + + match: + description: "Defines the step’s conditions to be matched." + $ref: "#/components/schemas/configRouteStepMatch" + + #/config/routes/{stepIndex}/match + #/config/routes/{routeName}/{stepIndex}/match + configRouteStepMatch: + type: object + description: "An object whose options define a step's conditions." + properties: + arguments: + description: "Arguments supplied with the request’s query string." + anyOf: + - $ref: "#/components/schemas/configRouteStepMatchObject" + - $ref: "#/components/schemas/configRouteStepMatchObjectArray" + + cookies: + description: "Cookies supplied with the request." + anyOf: + - $ref: "#/components/schemas/configRouteStepMatchObject" + - $ref: "#/components/schemas/configRouteStepMatchObjectArray" + + destination: + description: "Target IP address and optional port of the request." + $ref: "#/components/schemas/stringOrStringArray" + + headers: + description: "Header fields supplied with the request." + anyOf: + - $ref: "#/components/schemas/configRouteStepMatchObject" + - $ref: "#/components/schemas/configRouteStepMatchObjectArray" + + host: + description: "Host header field." + $ref: "#/components/schemas/stringOrStringArray" + + method: + description: "Method from the request line." + $ref: "#/components/schemas/stringOrStringArray" + + query: + description: "Query string." + $ref: "#/components/schemas/stringOrStringArray" + + scheme: + description: "URI scheme. Accepts only two patterns, + either `http` or `https`." + + enum: + - "http" + - "https" + + source: + description: "Source IP address and optional port of the request." + $ref: "#/components/schemas/stringOrStringArray" + + uri: + description: "Request target." + $ref: "#/components/schemas/stringOrStringArray" + + #/config/routes/{stepIndex}/match/[arguments|cookies|headers] + #/config/routes/{routeName}/{stepIndex}/match/[arguments|cookies|headers] + configRouteStepMatchObject: + type: object + description: "An object whose options define a set of conditions." + additionalProperties: + $ref: "#/components/schemas/stringOrStringArray" + + #/config/routes/{stepIndex}/match/[arguments|cookies|headers] + #/config/routes/{routeName}/{stepIndex}/match/[arguments|cookies|headers] + configRouteStepMatchObjectArray: + type: array + description: "An array whose items define sets of conditions." + items: + $ref: "#/components/schemas/configRouteStepMatchObject" + + #/config/routes/{stepIndex}/action + #/config/routes/{routeName}/{stepIndex}/action + configRouteStepAction: + type: object + description: "An object whose options define a step's action." + oneOf: + - $ref: "#/components/schemas/configRouteStepActionPass" + - $ref: "#/components/schemas/configRouteStepActionProxy" + - $ref: "#/components/schemas/configRouteStepActionReturn" + - $ref: "#/components/schemas/configRouteStepActionShare" + + #/config/routes/{stepIndex}/action/pass + #/config/routes/{routeName}/{stepIndex}/action/pass + configRouteStepActionPass: + type: object + description: "An object whose single option defines a step's pass action." + required: + - pass + properties: + pass: + type: string + description: "Destination to which the action passes + incoming requests." + + rewrite: + $ref: "#/components/schemas/configRouteStepActionRewrite" + + response_headers: + $ref: "#/components/schemas/configRouteStepActionResponseHeaders" + + #/config/routes/{stepIndex}/action/proxy + #/config/routes/{routeName}/{stepIndex}/action/proxy + configRouteStepActionProxy: + type: object + description: "An object whose single option defines a step's proxy + action." + required: + - proxy + properties: + proxy: + type: string + description: "Socket address of an HTTP server to where the request + is proxied." + + rewrite: + $ref: "#/components/schemas/configRouteStepActionRewrite" + + response_headers: + $ref: "#/components/schemas/configRouteStepActionResponseHeaders" + + #/config/routes/{stepIndex}/action/return + #/config/routes/{routeName}/{stepIndex}/action/return + configRouteStepActionReturn: + type: object + description: "An object whose single option defines a step's + return action." + + required: + - return + + properties: + return: + type: integer + description: "Defines the HTTP response status code to be returned." + + location: + type: string + description: "URI; used if the return value implies redirection." + + rewrite: + $ref: "#/components/schemas/configRouteStepActionRewrite" + + response_headers: + $ref: "#/components/schemas/configRouteStepActionResponseHeaders" + + #/config/routes/{stepIndex}/action/share + #/config/routes/{routeName}/{stepIndex}/action/share + configRouteStepActionShare: + type: object + description: "An object whose single option defines a step's + share action." + + required: + - share + + properties: + share: + description: "Lists file paths that are tried until a file is found." + $ref: "#/components/schemas/stringOrStringArray" + + index: + type: string + description: "Filename; tried if share is a directory." + default: "index.html" + + fallback: + description: "Used if the request can’t be served by share or index." + $ref: "#/components/schemas/configRouteStepAction" + + types: + description: "Used to filter the shared files." + $ref: "#/components/schemas/stringArray" + + chroot: + type: string + description: "Directory pathname that restricts the shareable paths." + + follow_symlinks: + type: boolean + description: "Turns on and off symbolic link resolution." + default: true + + traverse_mounts: + type: boolean + description: "Turns on and off mount point resolution." + default: true + + rewrite: + $ref: "#/components/schemas/configRouteStepActionRewrite" + + response_headers: + $ref: "#/components/schemas/configRouteStepActionResponseHeaders" + + #/config/routes/{stepIndex}/action/rewrite + #/config/routes/{routeName}/{stepIndex}/action/rewrite + configRouteStepActionRewrite: + type: string + description: "Updates the URI of the incoming request before the action + is applied." + + #/config/routes/{stepIndex}/action/response_headers + #/config/routes/{routeName}/{stepIndex}/action/response_headers + configRouteStepActionResponseHeaders: + type: object + description: "Updates the header fields of Unit’s response before the + action is taken." + additionalProperties: + type: string + + # /config/listeners/ + configListeners: + type: object + description: "An object whose options are listeners." + additionalProperties: + $ref: "#/components/schemas/configListener" + + # /config/listeners/{listenerName} + configListener: + type: object + description: "An individual listener." + properties: + tls: + $ref: "#/components/schemas/configListenerTls" + forwarded: + $ref: "#/components/schemas/configListenerForwarded" + pass: + type: string + description: "Destination to which the listener passes + incoming requests." + + # /config/listeners/{listenerName}/tls/certificate + configListenerTlsCertificate: + description: "Refers to one or more certificate bundles uploaded earlier." + anyOf: + - type: string + - $ref: "#/components/schemas/stringArray" + + # /config/listeners/{listenerName}/tls/conf_commands + configListenerTlsConfCommands: + type: object + description: "Defines the SSL configuration commands to be set for + the listener." + additionalProperties: + type: string + + # /config/listeners/{listenerName}/tls + configListenerTls: + type: object + description: "Defines SSL/TLS settings for the listener." + required: + - certificate + + properties: + conf_commands: + $ref: "#/components/schemas/configListenerTlsConfCommands" + + session: + $ref: "#/components/schemas/configListenerTlsSession" + + certificate: + $ref: "#/components/schemas/configListenerTlsCertificate" + + # /config/listeners/{listenerName}/tls/session + configListenerTlsSession: + type: object + description: "Configures the TLS session cache and tickets for + the listener." + + properties: + cache_size: + type: integer + description: "Number of sessions in the TLS session cache." + default: 0 + + timeout: + type: integer + description: "Session timeout for the TLS session cache in seconds." + default: 300 + + tickets: + $ref: "#/components/schemas/configListenerTlsSessionTickets" + + # /config/listeners/{listenerName}/tls/session/tickets + configListenerTlsSessionTickets: + description: "Configures TLS session tickets." + anyOf: + - type: boolean + - type: string + - $ref: "#/components/schemas/stringArray" + + default: false + + # /config/listeners/{listenerName}/forwarded + configListenerForwarded: + type: object + description: "Configures client IP address and protocol replacement." + required: + - source + + properties: + client_ip: + type: string + description: "Defines the HTTP header fields to expect in the request; + uses the `X-Forwarded-For` format." + + source: + description: "Defines address-based patterns for trusted addresses." + anyOf: + - type: string + - $ref: "#/components/schemas/stringArray" + + recursive: + type: boolean + description: "Controls how the `client_ip` fields are traversed." + default: false + + protocol: + description: "Defines the relevant HTTP header field to expect in the + request; uses the `X-Forwarded-Proto` format." + + enum: + - "http" + - "https" + - "on" + + # /config/settings + configSettings: + type: object + description: "An object whose single option represents global + Unit settings." + + properties: + http: + description: "Represents global HTTP settings in Unit." + $ref: "#/components/schemas/configSettingsHttp" + + # /config/settings/http + configSettingsHttp: + type: object + description: "An object whose options represent global HTTP settings + in Unit." + + properties: + body_read_timeout: + type: integer + description: "Maximum number of seconds to read data from the body of + a client’s request." + + default: 30 + + discard_unsafe_fields: + type: boolean + description: "If `true`, Unit only processes header names made of + alphanumerics and hyphens." + + default: true + + header_read_timeout: + type: integer + description: "Maximum number of seconds to read the header of a + client’s request." + + default: 30 + + idle_timeout: + type: integer + description: "Maximum number of seconds between requests in a + keep-alive connection." + + default: 180 + + log_route: + type: boolean + description: "Enables or disables router logging." + default: false + + max_body_size: + type: integer + description: "Maximum number of bytes in the body of a + client’s request." + + default: 8388608 + + send_timeout: + type: integer + description: "Maximum number of seconds to transmit data as a + response to the client." + default: 30 + + server_version: + type: boolean + description: "Enables or disables version numbers in Unit's `Server` + header fields." + + default: true + + static: + description: "Configures static asset handling." + $ref: "#/components/schemas/configSettingsHttpStatic" + + # /config/settings/http/static + configSettingsHttpStatic: + type: object + description: "An object whose single option defines specific MIME types." + properties: + mime_types: + $ref: "#/components/schemas/configSettingsHttpStaticMimeTypes" + + # /config/settings/http/static/mime_types + configSettingsHttpStaticMimeTypes: + type: object + description: "An object whose options define individual MIME types." + additionalProperties: + $ref: "#/components/schemas/configSettingsHttpStaticMimeType" + + # /config/settings/http/static/mime_types/{mimeType} + configSettingsHttpStaticMimeType: + description: "An entity that defines an individual MIME type by + listing file extensions." + + anyOf: + - type: string + - $ref: "#/components/schemas/stringArray" + + # /status + status: + description: "Represents Unit's usage statistics." + type: object + properties: + connections: + $ref: "#/components/schemas/statusConnections" + + requests: + $ref: "#/components/schemas/statusRequests" + + applications: + $ref: "#/components/schemas/statusApplications" + + # /status/applications + statusApplications: + description: "Lists Unit's application process and request statistics." + type: object + additionalProperties: + $ref: "#/components/schemas/statusApplicationsApp" + + # /status/applications/{appName} + statusApplicationsApp: + description: "Represents Unit's per-app process and request statistics." + type: object + properties: + processes: + $ref: "#/components/schemas/statusApplicationsAppProcesses" + + requests: + $ref: "#/components/schemas/statusApplicationsAppRequests" + + # /status/applications/{appName}/processes + statusApplicationsAppProcesses: + description: "Represents Unit's per-app process statistics." + type: object + properties: + running: + type: integer + description: "Current running app processes." + + starting: + type: integer + description: "Current starting app processes." + + idle: + type: integer + description: "Current idle app processes." + + # /status/applications/{appName}/requests + statusApplicationsAppRequests: + description: "Represents Unit's per-app request statistics." + type: object + properties: + active: + type: integer + description: "Active app requests." + + # /status/requests + statusRequests: + description: "Represents Unit's per-instance request statistics." + type: object + properties: + total: + type: integer + description: "Total non-API requests during the instance’s lifetime." + + # /status/connections + statusConnections: + description: "Represents Unit's per-instance connection statistics." + type: object + properties: + accepted: + type: integer + description: "Total accepted connections during the + instance’s lifetime." + + active: + type: integer + description: "Current active connections for the instance." + + idle: + type: integer + description: "Current idle connections for the instance." + + closed: + type: integer + description: "Total closed connections during + the instance’s lifetime." + +# -- TAGS -- + +tags: + - name: access log + description: Everything about the access log in the /config section + externalDocs: + url: https://unit.nginx.org/configuration/#access-log + + - name: apps + description: Everything about applications + externalDocs: + url: https://unit.nginx.org/configuration/#applications + + - name: certificates + description: + Everything about the /certificates section in Unit's control API + in Unit's control API + externalDocs: + url: https://unit.nginx.org/certificates/ + + - name: config + description: Everything about the /config section in Unit's control API + externalDocs: + url: https://unit.nginx.org/configuration/ + + - name: control + description: Everything about the /control section in Unit's control API + externalDocs: + url: https://unit.nginx.org/controlapi/ + + - name: listeners + description: Everything about listeners in the /config section + externalDocs: + url: https://unit.nginx.org/configuration/#listeners + + - name: routes + description: Everything about routes in the /config section + externalDocs: + url: https://unit.nginx.org/configuration/#routes + + - name: settings + description: Everything about the global settings in the /config section + externalDocs: + url: https://unit.nginx.org/configuration/#settings + + - name: status + description: Everything about the /status section in Unit's control API + externalDocs: + url: https://unit.nginx.org/usagestats/ + + - name: tls + description: Everything about SSL/TLS in Unit's control API + externalDocs: + url: https://unit.nginx.org/certificates/ + + - name: xff + description: Everything about X-Forwarded-* handling in Unit's control API + externalDocs: + url: https://unit.nginx.org/configuration/#ip-protocol-forwarding + +externalDocs: + description: "Find us on GitHub" + url: "https://github.com/nginx/unit" \ No newline at end of file