@ -15,24 +15,33 @@ Architecture
------------
The **software setup** and installation of OPNsense® is available
for the `x86-64 <https://en.wikipedia.org/wiki/X86-64> `__ bit microprocessor
for the `x86-64 <https://en.wikipedia.org/wiki/X86-64> `__ microprocessor
architecture only.
----------------
Embedded vs Full
----------------
Full installs can run on `SD memory
cards <https://en.wikipedia.org/wiki/Secure_Digital>`__, `
disks (SSD) <https://en.wikipedia.org/wiki/Solid-state_drive>`__ or
`hard disk drives
OPNsense offers two Image types with all major releases: embedded and full images.
The Embedded Image is intended for environments where preinstalling
the storage media is required due to a lack of local resources on the firewall
like storage, and/or console access (VGA/Serial). The image is tailored to reduce
write cycles as well, but the image can be used anywhere. Another reason for the
Embedded Image is to eliminate the need for local console access for installing OPNsense.
Installation is managed by prewriting the image to a storage device, installing the
storage device, and booting the system.
Full Images provide installation tools like OPNsense Importer, Live Environment,
and Installer. Full Images are released to support different console/hardware installation
requirements.
Both image types can be installed and run from virtual disks (VM), `SD memory
cards <https://en.wikipedia.org/wiki/Secure_Digital>`__,
USB disks, `solid-state
disks (SSD) <https://en.wikipedia.org/wiki/Solid-state_drive>`__, or `
(HDD) <https://en.wikipedia.org/wiki/Hard_disk_drive>`__.
Since version 15.1.10 (04 May 2015) the option to install an
`embedded <https://en.wikipedia.org/wiki/Embedded_operating_system> `__
OPNsense image is also supported.
The main differences between an embedded image and a full image are:
The main differences between embedded and full images are:
+-----------------------+-----------------------+
| Embedded | Full |
@ -50,117 +59,55 @@ The main differences between an embedded image and a full image are:
+-----------------------+-----------------------+
Embedded images (nano) store logging and cache data in memory only, while full versions
Embedded image store logging and cache data in memory only, while full versions
will keep the data stored on the local drive. A full version can mimic the
behavior of an embedded version by enabling RAM disks, this is especially
useful for SD memory card installations.
.. Warning ::
See the chapter :doc: `Hardware Setup <hardware>` for
further information on hardware requirements prior to an install.
-------------------------
Download and verification
-------------------------
The OPNsense distribution can be `downloaded <https://opnsense.org/download> `__
from one of our `mirrors <https://opnsense.org/download> `__ .
The OpenSSL tool is used for file verification.
4 files are needed for verification:
* The bzip compressed ISO file (<filename>.iso.bz2)
* The SHA-256 checksum file (<filename>.sha256)
* The signature file (<filename>.sig)
* The openssl public key (<filename>.pub)
These files can be downloaded from one of the download mirrors. To download them:
1. Go to the OPNSense `download <https://opnsense.org/download> `__ page.
2. After selecting a mirror, right click the download button and click "open in new tab".
3. A popup will appear asking if you want to download the image. Say "no" for now.
4. Remove the file name after the last slash in the URL bar, and press enter. This will take you to the directory listing for that mirror.
I.e. If you wanted to download from the US East Coast mirror:
Opening the link in a new tab would take you to this link:
`` mirror.wdc1.us.leaseweb.net/opnsense/releases/22.7/OPNsense-22.7-OpenSSL-dvd-amd64.iso.bz2 ``
You should take off the file name at the end, like this:
`` mirror.wdc1.us.leaseweb.net/opnsense/releases/22.1/ ``
The OpenSSL public key is required to verify against. This file is also on
the mirror directory listing page, however you should not trust the copy
there. Download it, open it up, and verify that the public key matches the
one from other sources. If it does not, the mirror may have been hacked,
or you may be the victim of a man-in-the-middle attack. Some other sources
to get the public key from include:
* https://pkg.opnsense.org/releases/mirror/README
* https://forum.opnsense.org/index.php?board=11.0
* https://opnsense.org/blog/
* https://github.com/opnsense/changelog/tree/master/community
* https://pkg.opnsense.org (/<FreeBSD version & architecture>/<release version>/sets/changelog.txz) (lands signed and verified in the GUI of the running software)
Note that only release announcements with images (typically all major
releases) contain the public key. I.e. 22.1 would have a copy of the public
key in the release announcement, but 22.1.9 would not.
Once you have downloaded all the required files and a copy of the public key,
and verified that the public key matches the public key from the alternate
sources listed above, you can be relatively certain that the key has not
been tampered with. To verify the downloaded image, run the following
commands (substituting the names in brackets for the files you downloaded):
`` openssl base64 -d -in <filename>.sig -out /tmp/image.sig ``
`` openssl dgst -sha256 -verify <key>.pub -signature /tmp/image.sig <image>.img.bz2 ``
Make sure to change the "img" to "iso" in the second line if you downloaded
a different installer type.
If the output of the second command is "Verified OK", your image was verified
successfully, and you can install it. If it has any other output, you may have
made an error using the commands, or the image may have been compromised.
See the chapter :doc: `Hardware Sizing & Setup <hardware>` for further information
on hardware requirements prior to an install.
------------------
Installation Media
Installation Images
------------------
Depending on you hardware and use case different installation media are provided :
+--------+---------------------------------------------------+
|Type | Description |
+========+===================================================+
| dvd | ISO installer image with live system capabilities |
| | running in VGA-only mode with UEFI support |
+--------+---------------------------------------------------+
| vga | USB installer image with live system capabilities |
| | running in VGA-only mode with UEFI support |
+--------+---------------------------------------------------+
| serial | USB installer image with live system capabilities |
| | running in serial console (115200) mode only |
| | with UEFI support |
+--------+---------------------------------------------------+
| nano | A preinstalled image for >=4 GB USB sticks, |
| | SD or CF cards for use with embedded devices |
| | running in serial console (115200) mode with |
| | secondary VGA support (no kernel messages though) |
+--------+---------------------------------------------------+
Depending on your hardware and use case, different installation options are available:
+--------+---------------------------------------------------+------------+
| Type | Description | Image Type |
+========+===================================================+============+
| dvd | ISO image boots into a live environment in | Full |
| | VGA-only mode with UEFI support | |
+--------+---------------------------------------------------+------------+
| vga | USB image boots into a live environment | Full |
| | in VGA-only mode with UEFI support | |
+--------+---------------------------------------------------+------------+
| serial | USB image boots into live environment running in | Full |
| | serial console (115200) mode only with | |
| | UEFI support | |
+--------+---------------------------------------------------+------------+
| nano | Image for preinstalling onto >=4 GB USB drives, | Embedded |
| | SD, or CF cards for use with embedded devices | |
| | running in serial console (115200) mode with | |
| | secondary VGA support (no kernel messages though) | |
+--------+---------------------------------------------------+------------+
.. Warning ::
Flash memory cards will only tolerate a limited number of writes
and re-writes. For embedded (nano) versions memory disks for /var and /tmp are
applied by default to prolong CF (flash) card lifetimes.
.. Note ::
All Full Image types can run both **`OPNsense Importer <https://docs.opnsense.org/manual/install.html#opnsense-importer>`**
before booting into the Live environment and also run
**`Installer <https://docs.opnsense.org/manual/install.html#install-to-target-system>`** once booted into the Live environment.
To enable for non embedded versions: Go to :menuselection: `System --> Settings --> Miscellaneous --> Disk / Memory Settings` ,
change the setting, then reboot. Consider to enable an external syslog server as well.
.. Warning ::
Flash memory cards will only tolerate a limited number of writes and re-writes. For
Nano image memory disks for **/var/log** and **/tmp** are applied by
default to prolong CF (flash) card lifetimes.
To enable non-embedded versions: Go to :menuselection: `System --> Settings --> Miscellaneous --> Disk / Memory Settings` ,
change the setting, then reboot. Consider enabling an external syslog server as well.
------------------------------
Media Filename Composition
Image Filename Composition
------------------------------
.. blockdiag ::
@ -209,77 +156,100 @@ Media Filename Composition
}
.. Note ::
**Please** be aware that the latest installation media does not always correspond
with the latest released version available. OPNsense installation images are provided
on a scheduled basis with major release versions in January and July. More information
on our release schedule is available from our package repository, see
`README <https://pkg.opnsense.org/releases/mirror/README>`
OPNsense after installation to be on the latest release available, see
`Update Page <https://docs.opnsense.org/manual/updates.html>`
**Please** be aware that the latest installation media does not always
correspond with the latest released version. OPNsense installation images are
provided on a regular basis together with major versions in January and July.
More information on our release schedule is available from our package
repository, see `README <https://pkg.opnsense.org/releases/mirror/README> `__
-------------------------
Download and Verification
-------------------------
--------------------
OpenSSL and LibreSSL
--------------------
The OPNsense distribution can be `downloaded <https://opnsense.org/download> `__
from one of our `mirrors <https://opnsense.org/download> `__ .
OPNsense images are provided based upon `OpenSSL <https://www.openssl.org> `__ .
The `LibreSSL <http://www.libressl.org> `__ flavor can be selected from within
the GUI (:menuselection: `System --> Firmware --> Settings` ). In order to apply your choice an update
must be performed after save, which can include a reboot of the system.
OpenSSL is used for image file verification. 4 files are needed for verification process:
.. image :: ./images/firmware_flavour.png
* The SHA-256 checksum file (<filename>.sha256)
* The bzip compressed Image file (<filename>.<image>.bz2)
* The signature file (<filename>.<image>.bz2.sig)
* The openssl public key (<filename>.pub)
Use one of the OPNsense mirrors to download these files:
-------------------------
Boot preparation
-------------------------
1. Go to the bottom of OPNSense `download <https://opnsense.org/download> `__ page.
2. Click one of the available mirrors closest to your location.
3. Download one of each file mentioned above for your Image type.
After preparing the installation media, we need to make sure we can access the console
(either via keyboard and [virtual]monitor or :doc: `serial connectivity<how-tos/serial_access>` ) and know how to
access the boot selection via the system bios. Often there's a (function) key one should press during initial boot.
The OpenSSL public key (.pub) is required to verify against. Although the file is
available on the mirror's repository, you should not trust the copy there. Download
it, open it up, and verify the public key matches the one from other sources. If it
does not, the mirror may have been hacked, or you may be the victim of a man-in-the-middle
attack. Some other sources to get the public key from include:
.. Tip ::
* https://pkg.opnsense.org/releases/mirror/README
* https://forum.opnsense.org/index.php?board=11.0
* https://opnsense.org/blog/
* https://github.com/opnsense/changelog/tree/master/community
* https://pkg.opnsense.org (/<FreeBSD:<version> :<architecture> /<release version>/sets/changelog.txz)
OPNsense devices from the `OPNsense shop <https://shop.opnsense.com/> `__ use :code: `<ESC>` to enter the bios and boot selection
options.
.. Note ::
Only major release announcements for images contain the public key, and update
release announcements will not. i.e. 22.1 will have a copy of the public key in the release
announcement, but 22.1.9 will not.
.. Note ::
Once you download all the required files and verify that the public key matches
the public key found in one of the alternate sources listed above, you can be relatively
confident that the key has not been tampered with. To verify the downloaded image, run
the following commands (substituting the filenames in brackets for the files you downloaded):
`` openssl sha256 OPNsense-<filename>.bz2 ``
Match the checksum command output with the checksum vaules in file `` OPNsense-<version>-OpenSSL-checksums-amd64.sha256 `` .
If the checksums don't match, redownload your image file. If checksums match continue with the verification commands.
`` openssl base64 -d -in OPNsense-<filename>.sig -out /tmp/image.sig ``
`` openssl dgst -sha256 -verify OPNsense-<filename>.pub -signature /tmp/image.sig OPNsense-<filename>.bz2 ``
If the output of the second command is “**Verified OK** ”, your image file was verified
successfully, and its safe to install from it. Any other outputs, and you may need
to check your commands for errors, or the image file may have been compromised.
Serial connectivity settings for DECXXXX devices can be found :doc: `here </hardware/serial_connectivity>`
-------------------
Installation Method
Installation Media
-------------------
Download the installation image from one of the mirrors listed on the `OPNsense
<https://opnsense.org/download/> `__ website.
Now that you have downloaded and verified the installation image from above. You must unpack the
image file before you can write the image to disk. For Unix-like OSes use `` bzip2 -d OPNsense-<filename>.bz2 ``
command. For Windows use an application like `7zip <https://www.7-zip.org/download.html> `_ . The `` .bz2 `` will
be removed from the end of the filename after command/applcation completes.
The easiest method of installation is the USB-memstick installer. If
your target platform has a serial interface choose the "serial" image.
If you need to know more about using the serial interface,
consult the :doc: `serial access how-to<how-tos/serial_access>` .
After unpacking the image you can create the installation media. The easiest method to install
OPNsense is to use USB "`vga <https://docs.opnsense.org/manual/install.html#installation-media> `_ "
Image. If your target platform has a serial console interface choose the
“`serial <https://docs.opnsense.org/manual/install.html#installation-media> `_ ” image. If you
need to know more about using the serial console interface, consult the :doc: `serial access how-to<how-tos/serial_access>` .
Write the image to a USB flash drive (>=1 GB) or an IDE hard disk,
either with dd under FreeBSD or under Windows with physdiskwrite
Write the image to a USB flash drive (>=1 GB) or hard disk, using either dd for Unix-like
OSes and for Windows use physdiskwrite, `Etcher <https://www.balena.io/etcher#download-etcher> `_ ,
or `Rufus <https://rufus.ie/> `_ .
Before writing an (iso) image you need to unpack it first (use bunzip2).
**FreeBSD**
::
dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/daX bs=16k
dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/daX bs=16k
Where X = the device number of your USB flash drive (check `` dmesg `` )
**Linux**
::
dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/sdX bs=16k
where X = the IDE device name of your USB flash drive (check with hdparm -i /dev/sdX)
(ignore the warning about trailing garbage - it's because of the digital signature)
**OpenBSD**
::
dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/rsd6c bs=16k
@ -288,113 +258,213 @@ The device must be the ENTIRE device (in Windows/DOS language: the 'C'
partition), and a raw I/O device (the 'r' in front of the device "sd6"),
not a block mode device.
**macOS**
**Linux**
::
sudo dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/sdX bs=16k
where X = the IDE device name of your USB flash drive (check with hdparm -i /dev/sdX)
(ignore the warning about trailing garbage - it's because of the digital signature)
**macOS**
::
sudo dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/rdiskX bs=64k
sudo dd if=OPNsense-##.#.##-[Type]-[Architecture].img of=/dev/rdiskX bs=64k
where r = raw device, and where X = the disk device number of your CF
card (check Disk Utility) (ignore the warning about trailing garbage -
it's because of the digital signature)
**Windows**
::
physdiskwrite -u OPNsense-##.#.##-[Type]-[Architecture].img
physdiskwrite -u OPNsense-##.#.##-[Type]-[Architecture].img
(use v0.3 or later!)
-------------------------
System Boot Preparation
-------------------------
After preparing the installation media, we need to make sure we can access the console
(either via keyboard and [virtual]monitor or :doc: `serial connectivity<how-tos/serial_access>` ). Next we need to know
how to access the boot menu or the system bios (UEFI) to boot from the installation media. Most times will be a function
(F#), Del, or ESC key that needs to pressed immediately after powering on (or rebooting) the system. Usually within the
first 2 to 3 seconds from powering up.
.. Tip ::
OPNsense devices from the `OPNsense shop <https://shop.opnsense.com/> `__ use :code: `<ESC>` to enter the bios and boot selection
options.
.. Note ::
Serial connectivity settings for DECXXXX devices can be found :doc: `here </hardware/serial_connectivity>`
-------------------------
Installation Instructions
-------------------------
..
Comment: Not sure how rubric:: are used. I would like to replace Installation Instructions rubric with
section above. I also don't know how :name: work
.. rubric :: Install Instructions
:name: install-to-system
The boot process gives you the opportunity to run several optional configuration
steps. It has been designed to always boot into a live environment in order to
be able to access the GUI or even SSH directly. If a timeout was missed simply
restart the boot procedure.
OPNsense installation boot process allows us to run several optional configuration steps. The
boot process was designed to always boot into the live environment, allowing us to access the
GUI or even SSH directly. If a timeout was missed, restart the boot procedure.
OPNsense Importer
-----------------
All images feature the new "opnsense-importer" utility, which is now invoked
instead of the early installer. You can stop the automatic timeout by pressing
any key. Afterwards you will have the opportunity to select a disk to import
from. If the option times out or the importer is exited without a disk selection,
the factory defaults will be used for the boot.
All Full Images have the OPNsense Importer feature that offers flexibility in
recovering failed firewalls, testing new releases without overwriting the current
installation by running the new version in memory with the existing configuration
or migrating configurations to new hardware installations. Using Importer is slightly
different between previous installs with existing configurations on disk vs new
installations/migrations.
For systems that have OPNsense installed, and the configuration intact. Here is the process:
#. Boot the system with installation media
#. Press any key when you see **“Press any key to start the configuration importer”** .
#. If you see OPNsense logo you have past the Importer and will need to reboot.
#. Type the device name of the existing drive that contains the configuration and press enter.
#. If Importer is successful, the boot process will continue into the Live environment using
the stored configuration on disk.
#. If Importer was unsuccessful, we will returned to the device selection prompt. Confirm the
device name is correct and try again. Otherwise, there maybe possible disk corruption and
restoring from backup.
The next prompt will be for manual interface selection.
This step is well-established since OPNsense 15.7 .
At this point the system will boot up with a fully functional firewall in Live enironment using existing configuration
but will not overwrite the previous installation. Use this feature for safely previewing or testing upgrades .
Live environment
For New installations/migrations follow this process:
#. We must have a 2nd USB drive formatted with FAT or FAT32 File system.
#. Preferable non-bootable USB drive.
#. Create a **conf** directory on the root of the USB drive
#. Place an *unencrypted* <downloaded backup>.xml into /conf and rename the file to **config.xml**
`` /conf/config.xml ``
#. Put both the Installation media and the 2nd USB drive into the system and power up / reboot.
#. Boot the system from the OPNsense Installation media via Boot Menu or BIOS (UEFI).
#. Press aany key when you see: **“Press any key to start the configuration importer”**
#. Type the device name of the 2nd USB Drive, e.g. `da0`
#. If Importer is successful, the boot process will continue into the Live environment using
the configuration stored on the USB drive.
#. If unsuccessful, importer will error and return us to the device selection prompt. Suggest
repeating steps 1-3 again.
Live Environment
----------------
The system will then continue into a live environment. If the config importer
was used previously on an existing installation, the system will boot up with a
fully functional setup, but will not overwrite the previous installation. Use
this feature for safely previewing upgrades.
If you have used a DVD, VGA, Serial image you are by default able to log into
the root shell using the user "root" with password "opnsense" to operate the
live environment.
The GUI will listen on https://192.168.1.1/ for user "root" with password
"opnsense" by default unless a previous configuration was imported. Using SSH,
the "root" and "installer" users are available as well on IP 192.168.1.1. Note
that these install medias are read-only, which means your current live
configuration will be lost after reboot.
Nano image
----------
If you have used a Nano image, your system is already up and running as it is
designed as such. It is set to read-write attempting to minimise write cycles by
mounting relevant partitions as memory file systems and reporting features
disabled by default.
..
Should we state the ability to manually identify network adapters before entering the live environment?
Create a bootable USB flash drive with the downloaded and unpacked image
file. Configure your system to boot from USB.
.. image :: ./images/opnsense_liveenv.png
Install to target system
------------------------
If you have used a DVD, VGA, Serial image you are by default able to start the
installer using the user "installer" with password "opnsense". On a previously
imported configuration the password will be the same as root's password.
After booting with an OPNsense Full Image (DVD, VGA, Serial), the firewall will
be in the Live environment with and without the use of OPNsense Importer. We
can interact with the Live environment via Local Console, GUI (HTTPS), or SSH.
Should the installer user not work for any reason, log in as user "root", select
option 8 from the menu and type "opnsense-installer". The "opnsense-importer" can
be run this way as well should you require to run the import again.
By default, we can log into the shell using the user `root`
`opnsense`
The installer can always be run to clone an existing system, even for Nano
images. This can be useful for creating live backups for later recovery.
The GUI is accessible at `https://192.168.1.1/ <https://192.168.1.1/>`
`root` `opnsense`
Using SSH we can access the firewall at IP `192.168.1.1` `root` `installer`
users are available, using password `opnsense`
.. Note ::
That the installation media is read-only, which means your current live configuration will
be lost after reboot.
The installation process involves a few simple steps.
Continue to :doc: `OPNsense Installer <OPNsense-Installer>` ` to install OPNsense to the local storage device .
OPNsense Installer
---------------------
.. Note ::
To invoke the installer login with user **installer** and password
**opnsense**
After successfully booting up with the OPNsense Full Image (DVD, VGA, Serial),
the firewall will be at the Live Environment's login: prompt. To start the
installation process, login with the user `` installer `` and password `` opnsense `` .
If Importer was used to import an existing configuration, the installer and root
user password would be the root password from the imported configuration.
If the installer user does not work, log in as user root and select: `` 8) Shell ``
from the menu and type `` opnsense-installer `` . The `` opnsense-importer `` can also
be run this way should you require to rerun the import.
..
Is this process documented anywhere? I'm having hard time understanding how a live
backup is created.
The installer can always be run to clone an existing system, even for Nano
images. This can be useful for creating live backups for later recovery.
.. Tip ::
The installer can also be started from the network using ssh, default ip
address is 192.168.1.1
#. Keymap selection - The default configuration should be fine for most
occasions.
#. Install (UFS|ZFS) - Choose either a UFS or ZFS filesystem. ZFS is in most
cases the best option as it is the most reliable option, but does require
enough memory (a couple of gigabytes at least).
#. Partitioning (ZFS) - Choose a device type. When using a single disk the
default option (stripe) is usually fine.
#. Continue with recommended swap (UFS) - Yes is usually fine here unless
the install target is very small (< 16GB)
#. Root Password - Choose a new root password
#. Complete Install - Exits the installer and reboots the machine
#. Reboot - The system is now installed and needs to be rebooted to
continue with configuration.
The installer can also be started from an inside host using ssh. Default ip
address is `` 192.168.1.1 ``
The installation process involves the following steps:
#. Keymap selection - The default configuration should be fine for most Occasions.
#. Install (UFS|ZFS) - Choose UFS or ZFS filesystem. ZFS is in most cases the best option
as it is the most reliable option, but it does require enough capacity (a couple of gigabytes at least).
#. Partitioning (ZFS) - Choose a device type. The default option (stripe) is usually acceptable
when using a single disk.
#. Disk Selection (ZFS) - Select the Storage device e.g. `` da0 `` or `` nvd0 ``
#. Last Chance! - Select Yes to continue with partitioning and to format the disk. However, doing
so will **destroy** the contents of the disk.
..
The installer on 23.1 does not mention or ask about swap anymore. Suggest we remove?
#. Continue with recommended swap (UFS) - Yes is usually fine here unless the install target
is very small (< 16GB)
#. Select Root Password - Change and confirm the new root password
#. Select Complete Install - Exits the installer and reboots the machine. The system is now installed
and ready for initial configuration.
..
Suggest we remove the warning as the install steps above covers this. If we keep it, then we should move
it to the top of the installation process. Also, there isn't Quick/Easy Install option. Is there?
.. Warning ::
You will lose all files on the installation disk. If another disk is to be
used then choose a Custom installation instead of the Quick/Easy Install.
Nano Image
----------
..
Commect: Moving Nano Image section after "Install to target system". We could move it
before "System Boot Preparation". Should we detail other default settings like interfaces, DHCP, etc?
Or are you prompted for interface assignment like Full Images?
To use the nano image follow this process:
#. Create the system disk with using the nano image. See :doc: `Installation Media<installation-media>`
how to write the nano image to disk.
#. Install the system disk drive into the system.
#. Configure the system (BIOS) to boot from this disk.
#. After the system boots, the firewall is ready to be configured.
Using the Nano image for embedded systems, your firewall is already up and running. The configuration
settings to enable Memory Disks (RAM disks) that minimize write cycles to relevant partitions by
mounting these partitions in system memory and reporting features are disabled by default.
---------------------
Initial configuration
Initial C onfiguration
---------------------
After installation the system will prompt you for the interface
assignment, if you ignore this then default settings are applied.
Nick H
1 year ago
committed by
GitHub
