rust_web_server/entry_point/command_line_args/
mod.rs

1use std::env;
2use crate::entry_point::Config;
3
4#[cfg(test)]
5mod tests;
6
7pub fn override_environment_variables_from_command_line_args() {
8    println!("\n  Start of Reading Command Line Arguments Section");
9
10    let args = env::args().collect();
11    let params = CommandLineArgument::get_command_line_arg_list();
12    CommandLineArgument::_parse(args, params);
13
14    println!("  End of Reading Command Line Arguments\n");
15}
16
17/// Returns the text to print for an informational flag — `--version` / `-V`
18/// or `--help` — if `args` (as from `env::args()`, program name first)
19/// contains one, so the binary can print it and exit before starting a
20/// server. `None` means start normally. `-h` is not a help alias: it's
21/// already `--cors-allow-headers`'s short form.
22pub fn informational_flag_output(args: &[String]) -> Option<String> {
23    let flags = args.iter().skip(1);
24    for arg in flags {
25        match arg.as_str() {
26            "--version" | "-V" => {
27                // A FIPS build says so (18.23.0); others print just the version.
28                return Some(format!("rws {}{}\n", env!("CARGO_PKG_VERSION"), if crate::FIPS { " (FIPS)" } else { "" }));
29            }
30            "--help" => return Some(help_text()),
31            _ => {}
32        }
33    }
34    None
35}
36
37fn help_text() -> String {
38    let mut text = format!(
39        "rws {} — HTTP/1.1, HTTP/2 and HTTP/3 web server and reverse proxy\n\n\
40         Usage: rws [OPTIONS]\n\n\
41         Serves the current directory on http://0.0.0.0:7878 by default. Drop an\n\
42         rws.config.toml with [[route]]/[[upstream]] sections in the working\n\
43         directory to run as a config-driven reverse proxy instead.\n\n\
44         Options (each also settable via the environment variable shown):\n",
45        env!("CARGO_PKG_VERSION")
46    );
47    for argument in CommandLineArgument::get_command_line_arg_list() {
48        let flag = if argument.short_form.is_empty() {
49            format!("    --{}=<value>", argument.long_form)
50        } else {
51            format!("-{}, --{}=<value>", argument.short_form, argument.long_form)
52        };
53        let hint = argument._hint.unwrap_or_default();
54        text.push_str(&format!("  {:<44} {}\n  {:<44} [env: {}]\n", flag, hint, "", argument.environment_variable));
55    }
56    text.push_str("      --check[=<file>]                         Validate rws.config.toml (or <file>) and exit:\n");
57    text.push_str("                                               0 if it has no errors, 1 otherwise\n");
58    text.push_str("      trust [--print] | untrust                Put rws's local CA (tls = \"internal\") in the\n");
59    text.push_str("                                               system trust store, or take it out\n");
60    text.push_str("      ctl <command>                            Drive a running server's admin API\n");
61    text.push_str("                                               (rws ctl help; also installed as rwsctl)\n");
62    text.push_str("  -V, --version                                Print version and exit\n");
63    text.push_str("      --help                                   Print this help and exit\n");
64    text.push_str("      --windows-service=<dir>                  (Windows) Run as a service serving <dir>\n\n");
65    text.push_str("Docs: https://rws8.tech\n");
66    text
67}
68
69pub struct CommandLineArgument {
70    pub short_form: String,
71    pub long_form: String,
72    pub environment_variable: String,
73    pub _hint: Option<String>,
74}
75
76impl CommandLineArgument {
77    pub fn get_command_line_arg_list() -> Vec<CommandLineArgument> {
78        let mut argument_list : Vec<CommandLineArgument> = vec![];
79
80        let argument = CommandLineArgument {
81            short_form: "p".to_string(),
82            long_form: "port".to_string(),
83            environment_variable: Config::RWS_CONFIG_PORT.to_string(),
84            _hint: Some("Port".to_string())
85        };
86        argument_list.push(argument);
87
88        let argument = CommandLineArgument {
89            short_form: "i".to_string(),
90            long_form: "ip".to_string(),
91            environment_variable: Config::RWS_CONFIG_IP.to_string(),
92            _hint: Some("IP or domain".to_string())
93        };
94        argument_list.push(argument);
95
96        let argument = CommandLineArgument {
97            short_form: "t".to_string(),
98            long_form: "thread-count".to_string(),
99            environment_variable: Config::RWS_CONFIG_THREAD_COUNT.to_string(),
100            _hint: Some("Number of threads".to_string())
101        };
102        argument_list.push(argument);
103
104
105        let argument = CommandLineArgument {
106            short_form: "a".to_string(),
107            long_form: "cors-allow-all".to_string(),
108            environment_variable: Config::RWS_CONFIG_CORS_ALLOW_ALL.to_string(),
109            _hint: Some("If set to true, will allow all CORS requests, other CORS properties will be ignored".to_string())
110        };
111        argument_list.push(argument);
112
113        let argument = CommandLineArgument {
114            short_form: "o".to_string(),
115            long_form: "cors-allow-origins".to_string(),
116            environment_variable: Config::RWS_CONFIG_CORS_ALLOW_ORIGINS.to_string(),
117            _hint: Some("Comma separated list of allowed origins, example: https://foo.example,https://bar.example".to_string())
118        };
119        argument_list.push(argument);
120
121        let argument = CommandLineArgument {
122            short_form: "m".to_string(),
123            long_form: "cors-allow-methods".to_string(),
124            environment_variable: Config::RWS_CONFIG_CORS_ALLOW_METHODS.to_string(),
125            _hint: Some("Comma separated list of allowed methods, example: POST,PUT".to_string())
126        };
127        argument_list.push(argument);
128
129        let argument = CommandLineArgument {
130            short_form: "h".to_string(),
131            long_form: "cors-allow-headers".to_string(),
132            environment_variable: Config::RWS_CONFIG_CORS_ALLOW_HEADERS.to_string(),
133            _hint: Some("Comma separated list of allowed request headers, in lowercase, example: content-type,x-custom-header".to_string())
134        };
135        argument_list.push(argument);
136
137        let argument = CommandLineArgument {
138            short_form: "c".to_string(),
139            long_form: "cors-allow-credentials".to_string(),
140            environment_variable: Config::RWS_CONFIG_CORS_ALLOW_CREDENTIALS.to_string(),
141            _hint: Some("If set to true, will allow to transmit credentials via CORS requests".to_string())
142        };
143        argument_list.push(argument);
144
145        let argument = CommandLineArgument {
146            short_form: "e".to_string(),
147            long_form: "cors-expose-headers".to_string(),
148            environment_variable: Config::RWS_CONFIG_CORS_EXPOSE_HEADERS.to_string(),
149            _hint: Some("Comma separated list of allowed response headers, in lowercase, example: content-type,x-custom-header".to_string())
150        };
151        argument_list.push(argument);
152
153        let argument = CommandLineArgument {
154            short_form: "g".to_string(),
155            long_form: "cors-max-age".to_string(),
156            environment_variable: Config::RWS_CONFIG_CORS_MAX_AGE.to_string(),
157            _hint: Some("How long results of preflight requests can be cached (in seconds)".to_string())
158        };
159        argument_list.push(argument);
160
161        let argument = CommandLineArgument {
162            short_form: "r".to_string(),
163            long_form: "request-allocation-size-in-bytes".to_string(),
164            environment_variable: Config::RWS_CONFIG_REQUEST_ALLOCATION_SIZE_IN_BYTES.to_string(),
165            _hint: Some("In bytes, how much memory to allocate for each request".to_string())
166        };
167        argument_list.push(argument);
168
169        let argument = CommandLineArgument {
170            short_form: "s".to_string(),
171            long_form: "tls-cert-file".to_string(),
172            environment_variable: Config::RWS_CONFIG_TLS_CERT_FILE.to_string(),
173            _hint: Some("Path to TLS certificate PEM file (enables HTTPS and HTTP/2)".to_string())
174        };
175        argument_list.push(argument);
176
177        let argument = CommandLineArgument {
178            short_form: "k".to_string(),
179            long_form: "tls-key-file".to_string(),
180            environment_variable: Config::RWS_CONFIG_TLS_KEY_FILE.to_string(),
181            _hint: Some("Path to TLS private key PEM file (enables HTTPS and HTTP/2)".to_string())
182        };
183        argument_list.push(argument);
184
185        // Long-form only (empty short_form): every single letter that reads
186        // naturally is taken. In rws.config.toml these are `http_redirect_port`
187        // at the top level and the keys of an `[acme]` section (`domains`,
188        // `email`, ...), which the config-file reader prefixes to `acme-*`.
189        let long_only = [
190            ("http-redirect-port", Config::RWS_CONFIG_HTTP_REDIRECT_PORT,
191                "Plain-HTTP port that 301-redirects to HTTPS (and answers ACME HTTP-01 challenges), e.g. 80"),
192            ("acme-domains", Config::RWS_CONFIG_ACME_DOMAINS,
193                "Comma separated domains to get a Let's Encrypt certificate for; enables automatic HTTPS"),
194            ("acme-email", Config::RWS_CONFIG_ACME_EMAIL,
195                "Contact email for the ACME account"),
196            ("acme-staging", Config::RWS_CONFIG_ACME_STAGING,
197                "If set to true, uses the Let's Encrypt staging environment (untrusted test certificates)"),
198            ("acme-directory", Config::RWS_CONFIG_ACME_DIRECTORY,
199                "ACME directory URL of a CA other than Let's Encrypt"),
200            ("acme-ca-file", Config::RWS_CONFIG_ACME_CA_FILE,
201                "PEM file of extra root CAs to trust for the ACME directory (private ACME CAs)"),
202            ("acme-challenge-port", Config::RWS_CONFIG_ACME_CHALLENGE_PORT,
203                "Port the CA connects to for HTTP-01 challenges (default 80)"),
204            ("acme-cert-path", Config::RWS_CONFIG_ACME_CERT_PATH,
205                "Where to store the issued certificate (default: tls-cert-file, else .rws/acme/cert.pem)"),
206            ("acme-key-path", Config::RWS_CONFIG_ACME_KEY_PATH,
207                "Where to store the certificate's private key (default: tls-key-file, else .rws/acme/key.pem)"),
208            ("acme-profile", Config::RWS_CONFIG_ACME_PROFILE,
209                "Certificate profile to order, as the CA offers them (e.g. classic, tlsserver, shortlived)"),
210            ("acme-challenge", Config::RWS_CONFIG_ACME_CHALLENGE,
211                "How to prove control of the domains: http-01 (default), tls-alpn-01, dns-01 (wildcards) or dns-persist-01"),
212            ("acme-dns-provider", Config::RWS_CONFIG_ACME_DNS_PROVIDER,
213                "DNS-01: rfc2136 (DNS UPDATE), cloudflare, route53 or exec (a program)"),
214            ("acme-dns-server", Config::RWS_CONFIG_ACME_DNS_SERVER,
215                "DNS-01 rfc2136: the primary DNS server, host[:port]"),
216            ("acme-dns-zone", Config::RWS_CONFIG_ACME_DNS_ZONE,
217                "DNS-01: the zone of the records (found by SOA lookup when not set)"),
218            ("acme-dns-tsig-key", Config::RWS_CONFIG_ACME_DNS_TSIG_KEY,
219                "DNS-01 rfc2136: TSIG key name (the secret goes in RWS_CONFIG_ACME_DNS_TSIG_SECRET)"),
220            ("acme-dns-tsig-algorithm", Config::RWS_CONFIG_ACME_DNS_TSIG_ALGORITHM,
221                "DNS-01 rfc2136: hmac-sha256 (default) or hmac-sha512"),
222            ("acme-dns-exec", Config::RWS_CONFIG_ACME_DNS_EXEC,
223                "DNS-01 exec: program run as <program> present|cleanup <fqdn> <value>"),
224            ("acme-dns-propagation-secs", Config::RWS_CONFIG_ACME_DNS_PROPAGATION_SECS,
225                "DNS-01: seconds to wait for the record to be visible (default 120)"),
226            ("acme-dns-api-url", Config::RWS_CONFIG_ACME_DNS_API_URL,
227                "DNS-01 cloudflare/route53: API base URL instead of the provider's (the token goes in RWS_CONFIG_ACME_DNS_API_TOKEN)"),
228            ("acme-dns-zone-id", Config::RWS_CONFIG_ACME_DNS_ZONE_ID,
229                "DNS-01 cloudflare/route53: the zone's id, instead of looking it up"),
230            ("acme-redis", Config::RWS_CONFIG_ACME_REDIS,
231                "Redis host:port shared by replicas: one orders each certificate, all install it"),
232            ("acme-redis-prefix", Config::RWS_CONFIG_ACME_REDIS_PREFIX,
233                "Key prefix in that Redis (default rws:acme)"),
234            ("acme-on-demand", Config::RWS_CONFIG_ACME_ON_DEMAND,
235                "true: order a certificate at the first handshake for a name the ask endpoint allows"),
236            ("acme-on-demand-ask", Config::RWS_CONFIG_ACME_ON_DEMAND_ASK,
237                "On-demand TLS: URL asked ?domain=<name> before each order; 2xx allows it"),
238        ];
239        for (long_form, environment_variable, hint) in long_only {
240            argument_list.push(CommandLineArgument {
241                short_form: "".to_string(),
242                long_form: long_form.to_string(),
243                environment_variable: environment_variable.to_string(),
244                _hint: Some(hint.to_string()),
245            });
246        }
247
248        let argument = CommandLineArgument {
249            short_form: "".to_string(),
250            long_form: "tls".to_string(),
251            environment_variable: "RWS_CONFIG_TLS".to_string(),
252            _hint: Some("internal: HTTPS from rws's own CA (local development; see rws trust)".to_string())
253        };
254        argument_list.push(argument);
255
256        argument_list
257    }
258
259    pub fn _parse(args: Vec<String>, argument_list : Vec<CommandLineArgument>) -> Vec<CommandLineArgument> {
260        for unparsed_argument in args.iter() {
261
262            let boxed_split = unparsed_argument.split_once('=');
263            if boxed_split.is_some() {
264
265                let (parameter, value) = boxed_split.unwrap();
266                println!("\n    {}={}", parameter, crate::entry_point::shown(parameter, value));
267                let boxed_predefined_argument =
268                    argument_list
269                        .iter()
270                        .find(
271                            |predefined_argument| {
272                                let short_form = predefined_argument.short_form.to_string();
273                                let long_form = predefined_argument.long_form.to_string();
274                                let _param_short_form = ["-", &short_form].join("");
275                                let _param_long_form = ["--", &long_form].join("");
276
277                                (!short_form.is_empty() && parameter.eq(_param_short_form.as_str())) ||
278                                    parameter.eq(_param_long_form.as_str())
279                });
280                if boxed_predefined_argument.is_some() {
281                    let predefined_argument = boxed_predefined_argument.unwrap();
282                    CommandLineArgument::set_environment_variable(predefined_argument, value.to_string());
283                }
284
285            }
286        }
287        argument_list
288    }
289
290    pub fn set_environment_variable(argument: &CommandLineArgument, value: String) {
291        if value.contains('\0') {
292            // env::set_var panics on NUL; reachable from rws.config.toml values.
293            eprintln!("    Warning: value for --{} contains a NUL byte — ignored", argument.long_form);
294            return;
295        }
296        env::set_var(&argument.environment_variable, &value);
297        crate::server_config::invalidate();
298        println!("    Set env variable '{}' to value '{}'", argument.environment_variable, crate::entry_point::shown(&argument.environment_variable, &value));
299    }
300}
rust_web_server/entry_point/command_line_args/mod.rs

rust_web_server/entry_point/command_line_args/
mod.rs
