From 84b1c785fdbc528cbf72bcddccd91deb1a6371e2 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 21 May 2025 12:34:13 -0600 Subject: [PATCH 1/3] document VLANs --- docs/chapters/networking.rst | 142 +++++++++++++++++++---------------- 1 file changed, 78 insertions(+), 64 deletions(-) diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index cbf93b61..61739e67 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -1,6 +1,43 @@ Networking ========== +Host Network Configuration +-------------------------- + +Bastille will automatically add and remove IP addressess to specified interfaces +as jails are started and stopped. Below is an outline of how Bastille handles +different types of jail network configs. + +* VNET mode. For VNET jails (non-bridged) bastille will create a bridge + interface and attach your jail to it. It will be called ``em0bridge`` or + whatever your interface is called. This will be used for the host/jail epairs. + Bastille will create/destroy these epairs as the jail is started/stopped. + +* Bridged VNET mode. For bridged VNET jails, you must manually create a bridge + interface to attach your jail to. Bastille will then create and attach the + host/jail epairs to this interface when the jail starts, and remove them when + it stops. + +* Alias mode. For classic/standard jails that use an IP that is accessible + within your local subnet (alias mode) bastille will add the IP to the + specified interface as an alias. + +* NAT mode. For classic/standard jails that use an IP not reachable in you local + subnet, bastille will add the IP to the specified interface as an alias, and + additionally add it the the pf firewall table to allow the jail outbound + access. If you do not specify an interface, Bastille will assume you have run + the ``bastille setup`` command and will attemplt to use ``bastille0`` (which + is created using the setup command) as it's interface. If you have not run + ``bastille setup`` and do not specify an interface, Bastille will error. + +* Inherit mode. For classic/standard jails that are set to ``inherit`` or + ``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the + jail config. The jail will then function according the jail(8) documentation. + +* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``, + bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. + The jail will then function according the jail(8) documentation. + IP Address Options ------------------ @@ -51,70 +88,6 @@ by quoting and IPv4 and IPv6 address together as seen in the following example. For the ``inherit`` and ``ip_hostname`` options, you can also specify ``-D|--dual`` to use both IPv4 and IPv6 inside the jail. -Host Network Configuration --------------------------- - -Bastille will automatically add and remove IP addressess to specified interfaces -as jails are started and stopped. Below is an outline of how Bastille handles -different types of jail network configs. - -* VNET mode. For VNET jails (non-bridged) bastille will create a bridge - interface and attach your jail to it. It will be called ``em0bridge`` or - whatever your interface is called. This will be used for the host/jail epairs. - Bastille will create/destroy these epairs as the jail is started/stopped. - -* Bridged VNET mode. For bridged VNET jails, you must manually create a bridge - interface to attach your jail to. Bastille will then create and attach the - host/jail epairs to this interface when the jail starts, and remove them when - it stops. - -* Alias mode. For classic/standard jails that use an IP that is accessible - within your local subnet (alias mode) bastille will add the IP to the - specified interface as an alias. - -* NAT mode. For classic/standard jails that use an IP not reachable in you local - subnet, bastille will add the IP to the specified interface as an alias, and - additionally add it the the pf firewall table to allow the jail outbound - access. If you do not specify an interface, Bastille will assume you have run - the ``bastille setup`` command and will attemplt to use ``bastille0`` (which - is created using the setup command) as it's interface. If you have not run - ``bastille setup`` and do not specify an interface, Bastille will error. - -* Inherit mode. For classic/standard jails that are set to ``inherit`` or - ``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the - jail config. The jail will then function according the jail(8) documentation. - -* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``, - bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. - The jail will then function according the jail(8) documentation. - -Network Scenarios ------------------ - -Here's the scenario. You've installed Bastille at home or in the cloud and want -to get started putting applications in secure little containers, but how do you -get these containers on the network? Bastille tries to be flexible about how to -network containerized applications. Four methods are described here. - -1. Home or Small Office - -2. Cloud with IPV4 and multiple IPV6 - -3. Cloud with single IPV4 (internal bridge) - -4. Cloud with a single IPV4 (external bridge) - -Please choose the option which is most appropriate for your environment. - -First a few notes. Bastille tries to verify that the interface name you provide -is a valid interface. In FreeBSD network interfaces have different names, but -look something like ``em0``, ``bge0``, ``re0``, ``vtnet0`` etc. Running the -``ifconfig`` command will tell you the name of your existing interfaces. -Bastille also checks for a valid syntax IP4 or IP6 address. When you are testing -calling out from your containers, please note that the ping command is disabled -within the containers, because raw socket access are a security hole. Instead, -install and test with ``wget/curl/fetch`` instead. - Shared Interface ---------------- @@ -329,6 +302,47 @@ on your system is. ifconfig_bridge0_name="bastille0bridge" ifconfig_bastille0bridge="addm vtnet0 up" +VLAN Configuration +------------------ + +Bastille supports VLANs to some extent when creating jails. When creating a jail, use +the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set the proper +variables inside the jails `rc.conf` to add the jail to the specified VLAN. + +You cannot use the ``-V`` options with interfaces that have dots (.) in the name, which is the +standard way of naming a VLAN interface. This is due to the limitations +of the JIB script that Bastille uses to manage VNET jails. + +You can however use ``-B`` with VLAN interfaces (even with dots in the name). Below +is an ``rc.conf`` snippet that was provided by a user who has such a configuration. + +.. code-block:: shell + + # rename ethernet interfaces + ifconfig_igb1_name="eth1" + ifconfig_eth1_descr="vm/jail ethernet interface" + + # setup vlans + vlans_eth1="10 20 30" + + # setup bridges + cloned_interfaces="bridge10 bridge20 bridge30" + ifconfig_bridge10_name="eth1.10bridge" + ifconfig_bridge20_name="eth1.20bridge" + ifconfig_bridge30_name="eth1.30bridge" + ifconfig_eth1_10bridge="addm eth1.10 up" + ifconfig_eth1_20bridge="addm eth1.20 up" + ifconfig_eth1_30bridge="addm eth1.30 up" + + # bring interfaces up + ifconfig_eth1="up" + ifconfig_eth1_10="up" + ifconfig_eth1_20="up" + ifconfig_eth1_30="up" + +Notice that the interfaces are bridge interfaces, and can be used with ``-B`` +without issue. + Regarding Routes ---------------- From ec32a2c17d0f93277d15ad188b6d223189d1a303 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 21 May 2025 18:06:35 -0600 Subject: [PATCH 2/3] Resolve reviews --- docs/chapters/networking.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 61739e67..7ee3eecc 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -4,25 +4,25 @@ Networking Host Network Configuration -------------------------- -Bastille will automatically add and remove IP addressess to specified interfaces +Bastille will automatically add and remove IP addresses to specified interfaces as jails are started and stopped. Below is an outline of how Bastille handles -different types of jail network configs. +different types of jail network configurations. -* VNET mode. For VNET jails (non-bridged) bastille will create a bridge +* VNET mode: For VNET jails (``-V``) Bastille will create a bridge interface and attach your jail to it. It will be called ``em0bridge`` or whatever your interface is called. This will be used for the host/jail epairs. Bastille will create/destroy these epairs as the jail is started/stopped. -* Bridged VNET mode. For bridged VNET jails, you must manually create a bridge +* Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a bridge interface to attach your jail to. Bastille will then create and attach the host/jail epairs to this interface when the jail starts, and remove them when it stops. -* Alias mode. For classic/standard jails that use an IP that is accessible +* Alias mode: For classic/standard jails that use an IP that is accessible within your local subnet (alias mode) bastille will add the IP to the specified interface as an alias. -* NAT mode. For classic/standard jails that use an IP not reachable in you local +* NAT mode: For classic/standard jails that use an IP not reachable in you local subnet, bastille will add the IP to the specified interface as an alias, and additionally add it the the pf firewall table to allow the jail outbound access. If you do not specify an interface, Bastille will assume you have run @@ -30,11 +30,11 @@ different types of jail network configs. is created using the setup command) as it's interface. If you have not run ``bastille setup`` and do not specify an interface, Bastille will error. -* Inherit mode. For classic/standard jails that are set to ``inherit`` or +* Inherit mode: For classic/standard jails that are set to ``inherit`` or ``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the jail config. The jail will then function according the jail(8) documentation. -* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``, +* ip_hostname mode: For classic/standard jails that are set to ``ip_hostname``, bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. The jail will then function according the jail(8) documentation. From f6314c1188ff355e85d358f3fee1e4bd77e21e33 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 21 May 2025 18:11:49 -0600 Subject: [PATCH 3/3] Resolve reviews --- docs/chapters/networking.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 7ee3eecc..da90a9e1 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -19,15 +19,15 @@ different types of jail network configurations. it stops. * Alias mode: For classic/standard jails that use an IP that is accessible - within your local subnet (alias mode) bastille will add the IP to the + within your local subnet (alias mode) Bastille will add the IP to the specified interface as an alias. -* NAT mode: For classic/standard jails that use an IP not reachable in you local - subnet, bastille will add the IP to the specified interface as an alias, and - additionally add it the the pf firewall table to allow the jail outbound +* NAT mode: For classic/standard jails that use an IP not reachable in your local + subnet, Bastille will add the IP to the specified interface as an alias, and + additionally, add it to the pf firewall table (if available) to allow the jail outbound access. If you do not specify an interface, Bastille will assume you have run - the ``bastille setup`` command and will attemplt to use ``bastille0`` (which - is created using the setup command) as it's interface. If you have not run + the ``bastille setup`` command and will attempt to use ``bastille0`` (which + is created using the setup command) as its interface. If you have not run ``bastille setup`` and do not specify an interface, Bastille will error. * Inherit mode: For classic/standard jails that are set to ``inherit`` or