apiclient: add network configure subcommand

Implements 'apiclient network configure <input-source>' to enable runtime
network configuration for Bottlerocket. stdin is the default input, but also
supports file://, base64: input sources with client-side URI processing.
Content is sent to the API server for further processing.

Signed-off-by: Yutong Sun <yutongsu@amazon.com>
Signed-off-by: Kyle Sessions <kssessio@amazon.com>

Author: ytsssun

sources/api/apiclient/README.md

@@ -5,7 +5,7 @@ Current version: 0.1.0
 ## apiclient binary
 
 The `apiclient` binary provides high-level methods to interact with the Bottlerocket API.
-There's a [set](#set-mode) subcommand for changing settings, an [update](#update-mode) subcommand for updating the host, and an [exec](#exec-mode) subcommand for running commands in host containers.
+There's a [set](#set-mode) subcommand for changing settings, a [network configure](#network-configure) subcommand for configuring network settings, an [update](#update-mode) subcommand for updating the host, and an [exec](#exec-mode) subcommand for running commands in host containers.
 There's also a low-level [raw](#raw-mode) subcommand for direct interaction with the HTTP API.
 
 It talks to the Bottlerocket socket by default.
@@ -75,6 +75,52 @@ You can use JSON form to set it:
 apiclient set --json '{"motd": "42"}'
 ```
 
+### Network configure
+
+This allows you to configure network settings by providing a network configuration file. The configuration will be applied at the next boot.
+
+The `network configure` command accepts input from different sources using URI schemes:
+
+#### File URI input
+
+You can specify a local file path using the `file://` URI scheme:
+
+```shell
+apiclient network configure file:///path/to/net.toml
+```
+
+#### Base64 encoded input
+
+For inline configuration, you can provide base64-encoded content:
+
+```shell
+apiclient network configure base64:dmVyc2lvbiA9IDIKCltldGgwXQpkaGNwNCA9IHRydWU=
+```
+
+This is particularly useful for automation and configuration management where you want to embed the network configuration directly in scripts or user data.
+
+#### Configuration format
+
+The `net.toml` file uses the same format that netdog supports. Here's an example:
+
+```toml
+version = 2
+
+[eth0]
+dhcp4 = true
+dhcp6 = false
+
+[eth1]
+static4 = ["192.168.1.100/24"]
+route = [{to = "default", via = "192.168.1.1"}]
+```
+
+After configuring the network settings, you'll need to reboot the system for the changes to take effect:
+
+```shell
+apiclient reboot
+```
+
 ### Update mode
 
 To start, you can check what updates are available:
@@ -347,7 +393,7 @@ The results from each item in the report will be one of:
 ## apiclient library
 
 The apiclient library provides high-level methods to interact with the Bottlerocket API.  See
-the documentation for submodules [`apply`], [`exec`], [`get`], [`reboot`], [`report`], [`set`],
+the documentation for submodules [`apply`], [`exec`], [`get`], [`network`], [`reboot`], [`report`], [`set`],
 and [`update`] for high-level helpers.
 
 For more control, and to handle APIs without high-level wrappers, there are also 'raw' methods

sources/api/apiclient/README.tpl

@@ -5,7 +5,7 @@ Current version: {{version}}
 ## apiclient binary
 
 The `apiclient` binary provides high-level methods to interact with the Bottlerocket API.
-There's a [set](#set-mode) subcommand for changing settings, an [update](#update-mode) subcommand for updating the host, and an [exec](#exec-mode) subcommand for running commands in host containers.
+There's a [set](#set-mode) subcommand for changing settings, a [network configure](#network-configure) subcommand for configuring network settings, an [update](#update-mode) subcommand for updating the host, and an [exec](#exec-mode) subcommand for running commands in host containers.
 There's also a low-level [raw](#raw-mode) subcommand for direct interaction with the HTTP API.
 
 It talks to the Bottlerocket socket by default.
@@ -75,6 +75,52 @@ You can use JSON form to set it:
 apiclient set --json '{"motd": "42"}'
 ```
 
+### Network configure
+
+This allows you to configure network settings by providing a network configuration file. The configuration will be applied at the next boot.
+
+The `network configure` command accepts input from different sources using URI schemes:
+
+#### File URI input
+
+You can specify a local file path using the `file://` URI scheme:
+
+```shell
+apiclient network configure file:///path/to/net.toml
+```
+
+#### Base64 encoded input
+
+For inline configuration, you can provide base64-encoded content:
+
+```shell
+apiclient network configure base64:dmVyc2lvbiA9IDIKCltldGgwXQpkaGNwNCA9IHRydWU=
+```
+
+This is particularly useful for automation and configuration management where you want to embed the network configuration directly in scripts or user data.
+
+#### Configuration format
+
+The `net.toml` file uses the same format that netdog supports. Here's an example:
+
+```toml
+version = 2
+
+[eth0]
+dhcp4 = true
+dhcp6 = false
+
+[eth1]
+static4 = ["192.168.1.100/24"]
+route = [{to = "default", via = "192.168.1.1"}]
+```
+
+After configuring the network settings, you'll need to reboot the system for the changes to take effect:
+
+```shell
+apiclient reboot
+```
+
 ### Update mode
 
 To start, you can check what updates are available:

sources/api/apiclient/src/lib.rs

@@ -1,5 +1,5 @@
 //! The apiclient library provides high-level methods to interact with the Bottlerocket API.  See
-//! the documentation for submodules [`apply`], [`exec`], [`get`], [`reboot`], [`report`], [`set`],
+//! the documentation for submodules [`apply`], [`exec`], [`get`], [`network`], [`reboot`], [`report`], [`set`],
 //! and [`update`] for high-level helpers.
 //!
 //! For more control, and to handle APIs without high-level wrappers, there are also 'raw' methods
@@ -24,6 +24,7 @@ pub mod ephemeral_storage;
 pub mod exec;
 pub mod get;
 pub mod lockdown;
+pub mod network;
 pub mod reboot;
 pub mod report;
 pub mod set;

sources/api/apiclient/src/main.rs

@@ -7,7 +7,8 @@
 // to the API, which is intended to be reusable by other crates.
 
 use apiclient::{
-    apply, ephemeral_storage, exec, get, lockdown, reboot, report, set, update, SettingsInput,
+    apply, ephemeral_storage, exec, get, lockdown, network, reboot, report, set, update,
+    SettingsInput,
 };
 use log::{info, log_enabled, trace, warn};
 use model::ephemeral_storage::{Filesystem, Preference};
@@ -49,6 +50,7 @@ enum Subcommand {
     Exec(ExecArgs),
     Get(GetArgs),
     Lockdown(LockdownArgs),
+    Network(NetworkSubcommand),
     Raw(RawArgs),
     Reboot(RebootArgs),
     Set(SetArgs),
@@ -185,6 +187,18 @@ struct EphemeralStorageFormatArgs {
     format: Option<String>,
 }
 
+/// Stores the 'network' subcommand specified by the user.
+#[derive(Debug)]
+enum NetworkSubcommand {
+    Configure(NetworkConfigureArgs),
+}
+
+/// Stores user-supplied arguments for the 'network configure' subcommand.
+#[derive(Debug)]
+struct NetworkConfigureArgs {
+    input_source: Option<String>,
+}
+
 /// Informs the user about proper usage of the program and exits.
 fn usage() -> ! {
     let msg = &format!(
@@ -203,6 +217,8 @@ fn usage() -> ! {
                                        or from stdin.
             get                        Retrieve and print settings.
             set                        Changes settings and applies them to the system.
+            network configure          Configures network settings from net.toml files at
+                                       given URIs.
             update check               Prints information about available updates.
             update apply               Applies available updates.
             update cancel              Deactivates an applied update.
@@ -248,6 +264,13 @@ fn usage() -> ! {
                                        If neither prefixes nor URI are specified, get will show
                                        settings and OS info.
 
+        network configure options:
+            [ URI ]                    URI to a network configuration file (TOML format)
+                                       to apply. Supports file:// and base64: URI schemes.
+                                       If no URI is specified, reads from stdin.
+                                       Configuration is written to /.bottlerocket/net.toml and
+                                       validated at next boot by netdog.
+
         set options:
             KEY=VALUE [KEY=VALUE ...]  The settings you want to set.  For example:
                                           settings.motd="hi there" settings.ecs.cluster=example
@@ -376,8 +399,8 @@ fn parse_args(args: impl Iterator<Item = String>) -> (Args, Subcommand) {
             }
 
             // Subcommands
-            "raw" | "apply" | "exec" | "get" | "lockdown" | "reboot" | "report" | "set"
-            | "update" | "ephemeral-storage"
+            "raw" | "apply" | "exec" | "get" | "lockdown" | "network" | "reboot" | "report"
+            | "set" | "update" | "ephemeral-storage"
                 if subcommand.is_none() && !arg.starts_with('-') =>
             {
                 subcommand = Some(arg)
@@ -395,6 +418,7 @@ fn parse_args(args: impl Iterator<Item = String>) -> (Args, Subcommand) {
         Some("exec") => (global_args, parse_exec_args(subcommand_args)),
         Some("get") => (global_args, parse_get_args(subcommand_args)),
         Some("lockdown") => (global_args, parse_lockdown_args(subcommand_args)),
+        Some("network") => (global_args, parse_network_args(subcommand_args)),
         Some("reboot") => (global_args, parse_reboot_args(subcommand_args)),
         Some("report") => (global_args, parse_report_args(subcommand_args)),
         Some("set") => (global_args, parse_set_args(subcommand_args)),
@@ -564,6 +588,42 @@ fn parse_lockdown_args(args: Vec<String>) -> Subcommand {
     }
     Subcommand::Lockdown(LockdownArgs {})
 }
+/// Parses the desired subcommand of 'network'.
+fn parse_network_args(args: Vec<String>) -> Subcommand {
+    let mut subcommand = None;
+    let mut subcommand_args = Vec::new();
+
+    for arg in args.into_iter() {
+        match arg.as_ref() {
+            // Subcommands
+            "configure" if subcommand.is_none() => subcommand = Some(arg),
+
+            // Other arguments are passed to the subcommand parser
+            _ => subcommand_args.push(arg),
+        }
+    }
+
+    match subcommand.as_deref() {
+        Some("configure") => parse_network_configure_args(subcommand_args),
+        _ => usage_msg("Missing or unknown subcommand for 'network'"),
+    }
+}
+
+/// Parses arguments for the 'network configure' subcommand.
+fn parse_network_configure_args(args: Vec<String>) -> Subcommand {
+    let mut input_source = None;
+
+    for arg in args.into_iter() {
+        if input_source.is_some() {
+            usage_msg("apiclient network configure takes only one input source URI.")
+        }
+        input_source = Some(arg);
+    }
+
+    Subcommand::Network(NetworkSubcommand::Configure(NetworkConfigureArgs {
+        input_source,
+    }))
+}
 
 /// Parses arguments for the 'reboot' subcommand.
 fn parse_reboot_args(args: Vec<String>) -> Subcommand {
@@ -1084,6 +1144,17 @@ async fn run() -> Result<()> {
                 .context(error::LockdownSnafu)?;
         }
 
+        Subcommand::Network(subcommand) => match subcommand {
+            NetworkSubcommand::Configure(configure_args) => {
+                let content = network::get_content(configure_args.input_source)
+                    .await
+                    .context(error::NetworkGetContentSnafu)?;
+                network::configure(&args.socket_path, content)
+                    .await
+                    .context(error::NetworkConfigureSnafu)?;
+            }
+        },
+
         Subcommand::Reboot(_reboot) => {
             reboot::reboot(&args.socket_path)
                 .await
@@ -1252,7 +1323,9 @@ async fn main() {
 }
 
 mod error {
-    use apiclient::{apply, ephemeral_storage, exec, get, lockdown, reboot, report, set, update};
+    use apiclient::{
+        apply, ephemeral_storage, exec, get, lockdown, network, reboot, report, set, update,
+    };
     use snafu::Snafu;
 
     #[derive(Debug, Snafu)]
@@ -1272,6 +1345,11 @@ mod error {
 
         #[snafu(display("Failed to lockdown: {}", source))]
         Lockdown { source: lockdown::Error },
+        #[snafu(display("Failed to get network configuration content: {}", source))]
+        NetworkGetContent { source: network::Error },
+
+        #[snafu(display("Failed to configure network: {}", source))]
+        NetworkConfigure { source: network::Error },
 
         #[snafu(display("Failed to reboot: {}", source))]
         Reboot { source: reboot::Error },
@@ -1515,4 +1593,66 @@ mod tests {
             _ => panic!("Expected Get with Prefixes"),
         }
     }
+
+    #[test]
+    fn test_network_configure_parsing_stdin() {
+        // Test that network configure with no arguments defaults to stdin
+        let (global_args, subcommand) = parse_command_line("apiclient network configure");
+
+        // Test global arguments match expected defaults
+        assert_eq!(global_args.log_level, LevelFilter::Info);
+        assert_eq!(global_args.socket_path, "/run/api.sock");
+
+        // Test network configure subcommand with no input source (stdin)
+        match subcommand {
+            Subcommand::Network(NetworkSubcommand::Configure(configure_args)) => {
+                assert_eq!(configure_args.input_source, None);
+            }
+            _ => panic!("Expected Network::Configure subcommand, got: {subcommand:?}"),
+        }
+    }
+
+    #[test_case("apiclient network configure file:///tmp/net.toml",
+        global_args!(LevelFilter::Info),
+        "file:///tmp/net.toml";
+        "network configure with file URI")]
+    #[test_case("apiclient network configure base64:dmVyc2lvbiA9IDIKCltldGgwXQpkaGNwNCA9IHRydWU=",
+        global_args!(LevelFilter::Info),
+        "base64:dmVyc2lvbiA9IDIKCltldGgwXQpkaGNwNCA9IHRydWU=";
+        "network configure with base64 URI")]
+    #[test_case("apiclient -v network configure file:///tmp/net.toml",
+        global_args!(LevelFilter::Debug),
+        "file:///tmp/net.toml";
+        "verbose flag with network configure")]
+    #[test_case("apiclient --log-level error network configure base64:test",
+        global_args!(LevelFilter::Error),
+        "base64:test";
+        "log level with network configure")]
+    #[test_case("apiclient --socket-path /tmp/custom.sock network configure file:///etc/net.toml",
+        global_args!(LevelFilter::Info, "/tmp/custom.sock"),
+        "file:///etc/net.toml";
+        "custom socket path with network configure")]
+    fn test_network_configure_parsing(
+        cmd_str: &str,
+        expected_args: Args,
+        expected_input_source: &str,
+    ) {
+        // Given a command line string for network configure
+        let (global_args, subcommand) = parse_command_line(cmd_str);
+
+        // Test global arguments match expected values
+        assert_eq!(global_args.log_level, expected_args.log_level);
+        assert_eq!(global_args.socket_path, expected_args.socket_path);
+
+        // Test network configure subcommand and extract input source
+        match subcommand {
+            Subcommand::Network(NetworkSubcommand::Configure(configure_args)) => {
+                assert_eq!(
+                    configure_args.input_source,
+                    Some(expected_input_source.to_string())
+                );
+            }
+            _ => panic!("Expected Network::Configure subcommand, got: {subcommand:?}"),
+        }
+    }
 }