opnsense/docs
1
0
Fork 0
mirror of https://github.com/opnsense/docs.git synced 2025-12-10 14:33:13 -06:00
Code Issues Packages Projects Releases Wiki Activity

Installation and setup: Grammar, punctuation, typo fixes and clarity adjustments (#805)

Browse Source
This commit is contained in:
Yang Ye 2025-11-26 19:35:51 +11:00 committed by GitHub
parent 7d85076915
commit c4be537f04
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 70 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
source/manual/hardware.rst
View File

@ -10,8 +10,8 @@ OPNsense.
pre-installed can be purchased directly from various (online) stores.
.. TIP::
The OPNsense development team encourage everyone looking for a turn-key solution
to buy from `Deciso <https://www.deciso.com>`__ or one of the other partners listed at our partner page.
The OPNsense development team encourages everyone looking for a turn-key solution
to buy from `Deciso <https://www.deciso.com>`__ or one of the other partners listed on our partner page.
**Listed partners make significant contributions back to the project.**
--------------------------------
@ -23,8 +23,8 @@ Full installs on `SD memory cards <https://en.wikipedia.org/wiki/Secure_Digital>
`solid-state disks (SSD) <https://en.wikipedia.org/wiki/Solid-state_drive>`__ or `hard disk drives
(HDD) <https://en.wikipedia.org/wiki/Hard_disk_drive>`__ are intended for OPNsense.
While the range of supported devices are from embedded systems to rack
mounted servers, the hardware must be capable of running 64-bit `operating
While supported devices range from embedded systems to rack-mounted servers,
the hardware must be capable of running 64-bit `operating
systems <https://en.wikipedia.org/wiki/operating_system>`__.
---------------------
@ -39,16 +39,16 @@ recommended specifications.
:name: minimum
The minimum specification to run all OPNsense standard features that do
not need disk writes, means you can run all standard features, except
not need disk writes means you can run all standard features, except
for the ones that require disk writes, e.g. a caching proxy (cache) or intrusion detection
and prevention (alert database).
+------------------+--------------------------------------------------------------------------+
| Processor | 1 GHz dual core cpu |
| Processor | 1 GHz dual-core CPU |
+------------------+--------------------------------------------------------------------------+
| RAM | 2 GB |
+------------------+--------------------------------------------------------------------------+
| Install method | Serial console or video (vga) |
| Install method | Serial console or video (VGA) |
+------------------+--------------------------------------------------------------------------+
| Install target | SD or CF card with a minimum of 4 GB, use nano images for installation. |
+------------------+--------------------------------------------------------------------------+
@ -58,16 +58,16 @@ Table: *Minimum hardware requirements*
.. rubric:: Reasonable
:name: reasonable
The reasonable specification to run all OPNsense standard features,
The reasonable specification to run all OPNsense standard features
means every feature is functional, but perhaps not with a lot of users
or high loads.
+------------------+--------------------------------------------------------------------------+
| Processor | 1 GHz dual core cpu |
| Processor | 1 GHz dual-core CPU |
+------------------+--------------------------------------------------------------------------+
| RAM | 4 GB |
+------------------+--------------------------------------------------------------------------+
| Install method | Serial console or video (vga) |
| Install method | Serial console or video (VGA) |
+------------------+--------------------------------------------------------------------------+
| Install target | 40 GB SSD, a minimum of 2 GB memory is needed for the installer to run. |
+------------------+--------------------------------------------------------------------------+
@ -77,15 +77,15 @@ Table: *Reasonable hardware requirements*
.. rubric:: Recommended
:name: recommended
The recommended specification to run all OPNsense standard features,
The recommended specification to run all OPNsense standard features
means every feature is functional and fits most use cases.
+------------------+---------------------------------+
| Processor | 1.5 GHz multi core cpu |
| Processor | 1.5 GHz multi-core CPU |
+------------------+---------------------------------+
| RAM | 8 GB |
+------------------+---------------------------------+
| Install method | Serial console or video (vga) |
| Install method | Serial console or video (VGA) |
+------------------+---------------------------------+
| Install target | 120 GB SSD |
+------------------+---------------------------------+
@ -95,33 +95,31 @@ Table: *Recommended hardware requirements*
.. rubric:: Hardware guide
:name: hardware-guide
The hardware required for your local OPNsense, will be determined by the
intended minimum `throughput <#throughput>`__ and the
feature set.
The hardware required for your local OPNsense will be determined by the
intended minimum `throughput <#throughput>`__ and feature set.
---------------------
Impact of Feature set
---------------------
While most features do not affect hardware dimensioning, a few features
have massive impact on it. The candidates are:
have a massive impact on it. These include:
`Squid <https://en.wikipedia.org/wiki/Squid_(software)>`__ 
a caching web proxy which can be used for web-content control,
respectively. These packages rely strongly on CPU load and
disk-cache writes.
A caching web proxy which can be used for web-content control.
These packages rely strongly on CPU load and disk-cache writes.
`Captive portal <https://en.wikipedia.org/wiki/Captive_portal>`__
settings with hundreds of simultaneously served captive portal users
Settings with hundreds of simultaneously served captive portal users
will require more CPU power in all the hardware specifications
displayed below.
`State transition tables <https://en.wikipedia.org/wiki/State_transition_table>`__
it is a known fact, that each state table entry requires about 1 kB
It is a known fact that each state table entry requires about 1 kB
(kilobytes) of RAM. The average state table, filled with 1000
entries will occupy about ~1 MB (megabytes) of
entries, will occupy about 1 MB (megabytes) of
`RAM <https://en.wikipedia.org/wiki/Random-access_memory>`__.
OPNsense usage settings with hundred of thousands of connections
OPNsense usage settings with hundreds of thousands of connections
will require memory accordingly.
|
@ -130,7 +128,7 @@ have massive impact on it. The candidates are:
Throughput
----------
The main hardware-factors of the OPNsense setup involved are CPU, RAM,
The main hardware factors of the OPNsense setup involved are CPU, RAM,
mass storage (disc), the number and quality of network interfaces.
+-------------------+-----------------------+-------------+------------------------+

74
source/manual/install.rst
View File

@ -3,8 +3,8 @@ Initial Installation & Configuration
=====================================
.. Note::
Just looking on how to invoke the installer? When the live environment has been
started just login with user **installer** and password **opnsense**.
Just looking for how to invoke the installer? When the live environment has been
started, log in with user **installer** and password **opnsense**.
.. contents:: Index
@ -57,9 +57,9 @@ The main differences between embedded and full images are:
+-----------------------+-----------------------+
Embedded image store logging and cache data in memory only, while full versions
The embedded image stores 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
behavior of an embedded version by enabling RAM disks, which is especially
useful for SD memory card installations.
.. Warning::
@ -98,8 +98,8 @@ Depending on your hardware and use case, different installation options are avai
.. 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.
the Nano image, **/var/log** and **/tmp** are memory disks by
default to prolong the lifetimes of CF/SD cards and SSDs in special cases.
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.
@ -173,13 +173,13 @@ from one of our `mirrors <https://opnsense.org/download>`__.
OpenSSL is used for image file verification. 4 files are needed for verification process:
* The SHA-256 checksum file (<filename>.sha256)
* The bzip compressed image file (<filename>.<image>.bz2)
* The bzip-compressed image file (<filename>.<image>.bz2)
* The signature file for the uncompressed image file (<filename>.<image>.sig)
* The openssl public key (<filename>.pub)
* The OpenSSL public key (<filename>.pub)
Use one of the OPNsense mirrors to download these files:
1. Go to the bottom of OPNSense `download <https://opnsense.org/download>`__ page.
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.
@ -212,7 +212,7 @@ the following commands (substituting the filenames in brackets for the files you
Match the checksum command output with the checksum values in the 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.
If the checksums match, continue with the verification commands.
::
@ -227,7 +227,7 @@ If checksums match continue with the verification commands.
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
successfully, and it is 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.
@ -235,7 +235,7 @@ to check your commands for errors, or the image file may have been compromised.
Installation Media
-------------------
Now that you have downloaded and verified the installation image from above. You must unpack the
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 the following command:
@ -253,7 +253,7 @@ Image. If your target platform has a serial console interface choose the
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 hard disk, using either dd for Unix-like
OSes and for Windows use physdiskwrite, `Etcher <https://www.balena.io/etcher#download-etcher>`_,
OSes or, for Windows, physdiskwrite, `Etcher <https://www.balena.io/etcher#download-etcher>`_,
or `Rufus <https://rufus.ie/>`_.
@ -303,14 +303,14 @@ 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
how to access the boot menu or the system BIOS (UEFI) to boot from the installation media. In most cases, it 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
OPNsense devices from the `OPNsense shop <https://shop.opnsense.com/>`__ use :code:`<ESC>` to enter the BIOS and boot selection
options.
.. Note::
@ -339,23 +339,23 @@ or migrating configurations to new hardware installations. Using Importer is sl
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:
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.
#. If you see the login prompt, you have passed 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
#. 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 be returned to the device selection prompt. Confirm the
device name is correct and try again. Otherwise, there may be possible disk corruption and
restoring from backup.
At this point the system will boot up with a fully functional firewall in Live enironment using existing configuration
At this point, the system will boot up with a fully functional firewall in live environment using existing configuration
but will not overwrite the previous installation. Use this feature for safely previewing or testing upgrades.
For New installations/migrations follow this process:
For new installations or migrations, follow this process:
#. We must have a 2nd USB drive formatted with FAT or FAT32 File system.
@ -365,13 +365,13 @@ For New installations/migrations follow this process:
#. Place an *unencrypted* <downloaded backup>.xml into /conf and rename the file to **config.xml** (:code:`/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”**
#. Press any key when you see: **“Press any key to start the configuration importer”**
#. Type the device name of the 2nd USB Drive, e.g. `da0` or `nvd0` , and press Enter.
#. 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.
#. If unsuccessful, the importer will error and return to the device selection prompt. In this
case, repeat steps 1-3 again.
Live Environment
----------------
@ -394,7 +394,7 @@ Using SSH we can access the firewall at IP **192.168.1.1** . Both the **root**
users are available with the password specified above.
.. Note::
That the installation media is read-only, which means your current live configuration will
The installation media is read-only, which means your current live configuration will
be lost after reboot.
Continue to `OPNsense Installer`_ to install OPNsense to the local storage device.
@ -402,34 +402,34 @@ Continue to `OPNsense Installer`_ to install OPNsense to the local storage devic
OPNsense Installer
---------------------
.. Note::
To invoke the installer login with user **installer** and password
To invoke the installer, log in 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.
user password will 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.
be run this way should you need to rerun the import.
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 an inside host using ssh. Default ip
The installer can also be started from an internal host using SSH. The default IP
address is ``192.168.1.1``
.. Attention::
When installing an appliance with SD or MMC flash card storage, ensure you select the UFS filesystem
and choose ``mmcsd0`` in the Disk Selection. Do not choose ``da0`` as that is the USB drive.
As example, this is applicable to the DEC677 Desktop Security Appliance.
As an example, this is applicable to the DEC677 Desktop Security Appliance.
The installation process involves the following steps:
#. Keymap selection - The default configuration should be fine for most Occasions.
#. 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
@ -453,7 +453,7 @@ Nano Image
To use the nano image follow this process:
#. Create the system disk with using the nano image. See `Installation Media`_
#. Create the system disk by using the Nano image. See `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.
@ -466,8 +466,8 @@ mounting these partitions in system memory and reporting features are disabled b
---------------------
Initial Configuration
---------------------
After installation the system will prompt you for the interface
assignment, if you ignore this then default settings are applied.
After installation, the system will prompt you for the interface
assignment. If you ignore this, then the default settings will be applied.
Installation ends with the login prompt.
By default you have to log in to enter the console.
@ -492,7 +492,7 @@ By default you have to log in to enter the console.
and password "opnsense".
VLANs and assigning interfaces
If choose to do manual interface assignment or when no config file can be
If you choose to do manual interface assignment or when no config file can be
found then you are asked to assign Interfaces and VLANs. VLANs are optional.
If you do not need VLANs then choose **no**. You can always configure
VLANs at a later time.
@ -500,7 +500,7 @@ VLANs and assigning interfaces
LAN, WAN and optional interfaces
The first interface is the LAN interface. Type the appropriate
interface name, for example "em0". The second interface is the WAN
interface. Type the appropriate interface name, eg. "em1" . Possible
interface. Type the appropriate interface name, e.g. "em1" . Possible
additional interfaces can be assigned as OPT interfaces. If you
assigned all your interfaces you can press [ENTER] and confirm the
settings. OPNsense will configure your system and present the login

8
source/manual/software_included.rst
View File

@ -12,7 +12,7 @@ install them when not installed by default.
The operating system
....................................
The basic ( `FreeBSD <https://www.freebsd.org/>`__) system contains a kernel and a base package, which provide the
The basic (`FreeBSD <https://www.freebsd.org/>`__) system contains a kernel and a base package, which provide the
bare essentials for the system to be able to boot and do its work.
Both components are updated using :code:`opnsense-update`, which is explained in more detail
@ -25,7 +25,7 @@ Plugins
Plugins are packages offered by OPNsense®, which can be installed directly via the user interface and often come
with setup options accessible for the end-user.
Since OPNsense® is a community driven project, the amount of (community/commercial) support available on these plugins
Since OPNsense® is a community-driven project, the amount of (community/commercial) support available on these plugins
can be different.
.. Note::
@ -49,7 +49,7 @@ To find a full list of all software available, you can use the following command
pkg rquery '%n (%v)'
If, for example you would like to install the gnu `nano <https://www.nano-editor.org/>`__ editor, you can do so using the following command:
For example, if you would like to install the gnu `nano <https://www.nano-editor.org/>`__ editor, you can do so using the following command:
.. code-block:: sh
@ -72,7 +72,7 @@ If, for example you would like to install the gnu `nano <https://www.nano-editor
The ports tree
....................................
In case you are using software, which is not supplied by us, you can always build these packages yourself.
In case you are using software which is not supplied by us, you can always build these packages yourself.
It's best to use our build system to facilitate this, you can do so using the following commands
.. code-block:: sh

12
source/manual/virtuals.rst
View File

@ -6,7 +6,7 @@ Virtual & Cloud based Installation
Local/Server
------------
Installing OPNsense on a virtual machine can be done by using the DVD ISO image.
Full instructions are available in chapter :doc:`install` .
Full instructions are available in chapter :doc:`install`.
General tips
------------
@ -75,7 +75,7 @@ Note: to install the VirtualBox guest additions just go to :menuselection:`Syste
Hosted
--------------------
For hosted installations where you can't install using the DVD ISO an alternative
For hosted installations where you cannot install using the DVD ISO, an alternative
approach is available in the form of **opnsense-bootstrap**.
opnsense-bootstrap
@ -91,8 +91,8 @@ package fingerprints.
What it will also do is turn a supported stock FreeBSD release into an OPNsense
installation. Both UFS and ZFS installations are supported.
opnsense bootstrap is available for our
`github source repository <https://github.com/opnsense/update/tree/master/bootstrap>`__
opnsense-bootstrap is available for our
`GitHub source repository <https://github.com/opnsense/update/tree/master/bootstrap>`__
@ -102,8 +102,8 @@ Amazon AWS EC2 Cloud
.. image:: how-tos/images/amazon-web-services.png
:height: 80px
Installing OPNsense into the Amazon cloud can be a daunting task as no console is
offered. Luckily an easy to install AMI is also available in the aws marketplace.
Installing OPNsense in Amazon Web Services can be a daunting task as no console is
offered. Luckily, an easy-to-install AMI is also available in the AWS marketplace.
See also our how-to for :doc:`how-tos/installaws`.