mirror of
https://github.com/hackacad/bastille.git
synced 2026-01-03 19:23:42 +01:00
doc: general reformatting to use 80 columns in the text
This commit is contained in:
Juan David Hurtado G
@@ -12,52 +12,88 @@ Bastille includes a number of IP options.
|
||||
|
||||
The IP address specified above can be any of the following options.
|
||||
|
||||
* An IP in your local subnet should be chosen if you create your jail using ``-V`` or ``-B`` (VNET jail). It is also preferable to add the subnet mask (/24 or whaterver your subnet is) to the IP.
|
||||
* An IP in your local subnet should be chosen if you create your jail using
|
||||
``-V`` or ``-B`` (VNET jail). It is also preferable to add the subnet mask
|
||||
(/24 or whaterver your subnet is) to the IP.
|
||||
|
||||
* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an address from your router. This should only be used with ``-V`` and ``-B``.
|
||||
* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an
|
||||
address from your router. This should only be used with ``-V`` and ``-B``.
|
||||
|
||||
* Any IP address inside the RFC1918 range if you are not using a VNET jail. Bastille will automatically add this IP to the firewall table to allow outbound access. It you want traffic to be forwarded into the jail, you can use the ``bastille rdr`` command.
|
||||
* Any IP address inside the RFC1918 range if you are not using a VNET jail.
|
||||
Bastille will automatically add this IP to the firewall table to allow
|
||||
outbound access. It you want traffic to be forwarded into the jail, you can
|
||||
use the ``bastille rdr`` command.
|
||||
|
||||
* Any IP in your local subnet without the ``-V`` or ``-B`` options will add the IP as an alias to the selected interface, which will simply end up sharing the interface. If the IP is in your local subnet, you will not need the ``bastille rdr`` command. Traffic will pass in and out just as in a VNET jail.
|
||||
* Any IP in your local subnet without the ``-V`` or ``-B`` options will add the
|
||||
IP as an alias to the selected interface, which will simply end up sharing the
|
||||
interface. If the IP is in your local subnet, you will not need the ``bastille
|
||||
rdr`` command. Traffic will pass in and out just as in a VNET jail.
|
||||
|
||||
* Setting the IP to ``inherit`` will make the jail inherit the entire host network stack.
|
||||
* Setting the IP to ``inherit`` will make the jail inherit the entire host
|
||||
network stack.
|
||||
|
||||
* Setting the IP to ``ip_hostname`` will add all the IPs that the hostname resolves to. This is an advanced option and should only be used if you know what you are doing.
|
||||
* Setting the IP to ``ip_hostname`` will add all the IPs that the hostname
|
||||
resolves to. This is an advanced option and should only be used if you know
|
||||
what you are doing.
|
||||
|
||||
Note that jails support specifying an IP without the subnet (/24 or whatever yours is) but we highly recommend setting it, especially
|
||||
on VNET jails. Not doing so can cause issues in some rare cases.
|
||||
Note that jails support specifying an IP without the subnet (/24 or whatever
|
||||
yours is) but we highly recommend setting it, especially on VNET jails. Not
|
||||
doing so can cause issues in some rare cases.
|
||||
|
||||
Bastille also supports IPv6. Instead of an IPv4 address, you can specify and IPv6 address when creating a jail to use IPv6. It is also possible to use both by quoting and IPv4 and IPv6 address together as seen in the following example.
|
||||
Bastille also supports IPv6. Instead of an IPv4 address, you can specify and
|
||||
IPv6 address when creating a jail to use IPv6. It is also possible to use both
|
||||
by quoting and IPv4 and IPv6 address together as seen in the following example.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
bastille create alcatraz 13.2-RELEASE "192.168.1.50/24 2001:19f0:6c01:114c:0:100/64" vtnet0
|
||||
|
||||
For the ``inherit`` and ``ip_hostname`` options, you can also specify ``-D|--dual`` to use both IPv4 and IPv6 inside the jail.
|
||||
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.
|
||||
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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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_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
|
||||
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
|
||||
@@ -72,12 +108,12 @@ 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
|
||||
commend 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.
|
||||
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 on Home or Small Office Network
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -107,7 +143,8 @@ interface and a free IP on your local network.
|
||||
Shared Interface on IPV6 network (vultr.com)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Some ISP's, such as `Vultr <https://vultr.com>`_, give you a single ipv4 address,
|
||||
Some ISP's, such as `Vultr <https://vultr.com>`_, give you a single ipv4
|
||||
address,
|
||||
and a large block of ipv6 addresses. You can then assign a unique ipv6 address
|
||||
to each Bastille Container.
|
||||
|
||||
@@ -131,7 +168,7 @@ The `vultr ipv6 subnet calculator
|
||||
<https://www.vultr.com/resources/subnet-calculator-ipv6/?prefix_length=64&display=long&ipv6_address=2001%3Adb8%3Aacad%3Ae%3A%3A%2F64>`_
|
||||
is helpful in making sense of that ipv6 address.
|
||||
|
||||
We could have also written that IPV6 address as 2001:19f0:6c01:114c:0:0
|
||||
We could have also written that IPV6 address as 2001:19f0:6c01:114c:0:0
|
||||
|
||||
Where the /64 basicaly means that the first 64 bits of the address (4x4
|
||||
character hexadecimal) values define the network, and the remaining characters,
|
||||
@@ -157,9 +194,9 @@ Virtual Network (VNET)
|
||||
|
||||
(Added in 0.6.x) VNET is supported on FreeBSD 12+ only.
|
||||
|
||||
Virtual Network (VNET) creates a private network interface for a container.
|
||||
This includes a unique hardware address. This is required for VPN, DHCP, and
|
||||
similar containers.
|
||||
Virtual Network (VNET) creates a private network interface for a container. This
|
||||
includes a unique hardware address. This is required for VPN, DHCP, and similar
|
||||
containers.
|
||||
|
||||
To create a VNET based container use the ``-V`` option, an IP/netmask and
|
||||
external interface.
|
||||
@@ -188,7 +225,7 @@ host system:
|
||||
.. code-block:: shell
|
||||
|
||||
## /etc/devfs.rules (NOT .conf)
|
||||
|
||||
|
||||
[bastille_vnet=13]
|
||||
add include $devfsrules_hide_all
|
||||
add include $devfsrules_unhide_basic
|
||||
@@ -224,27 +261,36 @@ Below is the definition of what these three parameters are used for and mean:
|
||||
Bridged Network (VNET bridged)
|
||||
------------------------------
|
||||
|
||||
To use a bridged VNET setup the first thing you have to do is to create a bridge interface on your system. This is done with the ifconfig command and will create a bridged interface named bridge0:
|
||||
To use a bridged VNET setup the first thing you have to do is to create a bridge
|
||||
interface on your system. This is done with the ifconfig command and will
|
||||
create a bridged interface named bridge0:
|
||||
|
||||
.. code-block:: shell
|
||||
ifconfig bridge create
|
||||
|
||||
Then you need to add your system's network interface to the bridge and bring it up (substitute your interface for em0).
|
||||
Then you need to add your system's network interface to the bridge and bring it
|
||||
up (substitute your interface for em0).
|
||||
|
||||
.. code-block:: shell
|
||||
ifconfig bridge0 addm em0 up
|
||||
|
||||
Optionally you can rename the interface if you wish to make it obvious that it is for bastille:
|
||||
Optionally you can rename the interface if you wish to make it obvious that it
|
||||
is for bastille:
|
||||
|
||||
.. code-block:: shell
|
||||
ifconfig bridge0 name bastille0bridge
|
||||
|
||||
To create a bridged container you use the ``-B`` option, an IP or DHCP, and the bridge interface.
|
||||
To create a bridged container you use the ``-B`` option, an IP or DHCP, and the
|
||||
bridge interface.
|
||||
|
||||
.. code-block:: shell
|
||||
bastille create -B folsom 14.2-RELEASE DHCP bastille0bridge
|
||||
|
||||
All the epairs and networking other than the manually created bridge will be created for you automagically. Now if you want this to persist after a reboot then you need to add some lines to your ``/etc/rc.conf`` file. Add the following lines, again, obviously change em0 to whatever your network interface on your system is.
|
||||
All the epairs and networking other than the manually created bridge will be
|
||||
created for you automagically. Now if you want this to persist after a reboot
|
||||
then you need to add some lines to your ``/etc/rc.conf`` file. Add the
|
||||
following lines, again, obviously change em0 to whatever your network interface
|
||||
on your system is.
|
||||
|
||||
.. code-block:: shell
|
||||
cloned_interfaces="bridge0"
|
||||
@@ -293,9 +339,10 @@ Public Network
|
||||
--------------
|
||||
|
||||
In this section we describe how to network containers in a public network
|
||||
such as a cloud hosting provider who only provides you with a single ip address.
|
||||
(AWS, Digital Ocean, etc) (The exception is vultr.com, which does
|
||||
provide you with lots of IPV6 addresses and does a great job supporting FreeBSD!)
|
||||
such as a cloud hosting provider who only provides you with a single ip address.
|
||||
(AWS, Digital Ocean, etc) (The exception is vultr.com, which does
|
||||
provide you with lots of IPV6 addresses and does a great job supporting
|
||||
FreeBSD!)
|
||||
|
||||
So if you only have a single IP address and if you want to create multiple
|
||||
containers and assign them all unique IP addresses, you'll need to create a new
|
||||
@@ -356,7 +403,8 @@ Create the firewall rules:
|
||||
antispoof for $ext_if inet
|
||||
pass in inet proto tcp from any to any port ssh flags S/SA modulate state
|
||||
|
||||
- Make sure to change the ``ext_if`` variable to match your host system interface.
|
||||
- Make sure to change the ``ext_if`` variable to match your host system
|
||||
interface.
|
||||
- Make sure to include the last line (``port ssh``) or you'll end up locked out.
|
||||
|
||||
Note: if you have an existing firewall, the key lines for in/out traffic
|
||||
@@ -405,7 +453,8 @@ This step only needs to be done once in order to prepare the host.
|
||||
local_unbound
|
||||
-------------
|
||||
|
||||
If you are running "local_unbound" on your server, you will probably have issues with DNS resolution.
|
||||
If you are running "local_unbound" on your server, you will probably have issues
|
||||
with DNS resolution.
|
||||
|
||||
To resolve this, add the following configuration to local_unbound:
|
||||
|
||||
@@ -416,6 +465,7 @@ To resolve this, add the following configuration to local_unbound:
|
||||
access-control: 192.168.0.0/16 allow
|
||||
access-control: 10.17.90.0/24 allow
|
||||
|
||||
Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf
|
||||
Also, change the nameserver to the servers IP instead of 127.0.0.1 inside
|
||||
/etc/rc.conf
|
||||
|
||||
Adjust the above "access-control" strings to fit your network.
|
||||
|
||||
Reference in New Issue
Block a user