mirror of https://github.com/opnsense/docs
Merge branch 'fabianfrz-contraints'
commit
f4244fb80b
@ -0,0 +1,144 @@
|
||||
==================================
|
||||
Adding constraints
|
||||
==================================
|
||||
|
||||
Constraints can be used on top of type validations provided by the base fields described in the previous chapter.
|
||||
The base class `BaseConstraint` is used as base type and contains shared functionality.
|
||||
|
||||
Since fields are usually only validated when there's change detected, it's usually necessary to add
|
||||
back references to chain validations.
|
||||
|
||||
DependConstraint
|
||||
-------------------------
|
||||
|
||||
When choices depend on each other, you can use the `DependConstraint` type.
|
||||
The following example makes `sslurlonly` depend on the `sslbump` option, since the `<reference>`
|
||||
tag is needed to make sure when one of the settings changes, the other is validated again too.
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<sslbump type="BooleanField">
|
||||
<Constraints>
|
||||
<check001>
|
||||
<type>DependConstraint</type>
|
||||
<addFields>
|
||||
<field1>sslurlonly</field1>
|
||||
</addFields>
|
||||
</check001>
|
||||
</Constraints>
|
||||
</sslbump>
|
||||
<sslurlonly type="BooleanField">
|
||||
<Constraints>
|
||||
<check001>
|
||||
<reference>sslbump.check001</reference>
|
||||
</check001>
|
||||
</Constraints>
|
||||
</sslurlonly>
|
||||
|
||||
|
||||
AllOrNoneConstraint
|
||||
-------------------------
|
||||
|
||||
Make sure that options are only valid when selected in combination.
|
||||
|
||||
SingleSelectConstraint
|
||||
-------------------------
|
||||
|
||||
When options are not valid in combination, you can hook options together so only one of the
|
||||
options can be selected at the same time.
|
||||
|
||||
UniqueConstraint
|
||||
-------------------------
|
||||
|
||||
This constraint helps to make sure all items within an `ArrayField` are unique, such as the following example
|
||||
which makes sure all "filenames" in this set are unique.
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<filename type="TextField">
|
||||
<Constraints>
|
||||
<check001>
|
||||
<type>UniqueConstraint</type>
|
||||
</check001>
|
||||
</Constraints>
|
||||
</filename>
|
||||
|
||||
|
||||
ComparedToFieldConstraint
|
||||
-------------------------
|
||||
|
||||
The ComparedToFieldConstraint compares the value of the current field to the value of a referenced field
|
||||
on the same level (for example in the same ArrayField).
|
||||
It is for example used for the rspamd_ plugin, to ensure that some values are in the correct order.
|
||||
This constraint can be used to compare numeric values.
|
||||
|
||||
.. _rspamd: https://github.com/opnsense/plugins/blob/master/mail/rspamd/src/opnsense/mvc/app/models/OPNsense/Rspamd/RSpamd.xml
|
||||
|
||||
Example:
|
||||
|
||||
::
|
||||
|
||||
<check003>
|
||||
<ValidationMessage>This field must be bigger than the greylist score.</ValidationMessage>
|
||||
<type>ComparedToFieldConstraint</type>
|
||||
<field>greylistscore</field>
|
||||
<operator>gt</operator>
|
||||
</check003>
|
||||
|
||||
In this example, the valueof the current field must be greater than the value of the field "greylistscore".
|
||||
|
||||
Field values:
|
||||
|
||||
================= ====================================================================================
|
||||
ValidationMessage Validation message (translateable) which will be shown in case the validation fails.
|
||||
type ComparedToFieldConstraint
|
||||
field the other field which we reference
|
||||
operator The operator to check the value. Valid operators are gt, gte, lt, lte, eq, neq
|
||||
================= ====================================================================================
|
||||
|
||||
Operators:
|
||||
|
||||
=== =====================
|
||||
gt greater than
|
||||
gte greater than or equal
|
||||
lt lesser than
|
||||
lte lesser than or equal
|
||||
eq equal
|
||||
neq not equal
|
||||
=== =====================
|
||||
|
||||
|
||||
|
||||
|
||||
SetIfConstraint
|
||||
------------------------------------
|
||||
|
||||
The SetIfConstraint is used to make some fields conditionally mandatory. It is mainly used in the nginx_
|
||||
plugin for example to choose an implementation type. In general the other field should be an OptionField,
|
||||
but does not need to. In general it is a good idea to hide or show fields which are (not)
|
||||
required by an implementation in the frontend as well to simplify the web interface.
|
||||
Please note: the checked field is intended to be on the same level (for example ArrayField).
|
||||
|
||||
.. _nginx: https://github.com/opnsense/plugins/blob/master/www/nginx/src/opnsense/mvc/app/models/OPNsense/Nginx/Nginx.xml
|
||||
|
||||
Example:
|
||||
|
||||
::
|
||||
|
||||
<check001>
|
||||
<ValidationMessage>This field must be set.</ValidationMessage>
|
||||
<type>SetIfConstraint</type>
|
||||
<field>match_type</field>
|
||||
<check>id</check>
|
||||
</check001>
|
||||
|
||||
In this example, the value will be mandatory, if the field "match_type" has the value "id".
|
||||
|
||||
Field Values:
|
||||
|
||||
================= ====================================================================================
|
||||
ValidationMessage Validation message (translateable) which will be shown in case the validation fails.
|
||||
type SetIfConstraint
|
||||
field the other field which we reference
|
||||
check The value of the other field which makes this field required
|
||||
================= ====================================================================================
|
@ -0,0 +1,194 @@
|
||||
----------------------
|
||||
Standard field types
|
||||
----------------------
|
||||
|
||||
OPNsense comes with a collection of standard field types, which can be used to perform standard field type validations.
|
||||
These field types can be found in `/usr/local/opnsense/mvc/app/models/OPNsense/Base/FieldTypes/ <https://github.com/opnsense/core/tree/master/src/opnsense/mvc/app/models/OPNsense/Base/FieldTypes>`__
|
||||
and usually decent from the `BaseField` type.
|
||||
|
||||
This paragraph aims to provide an overview of the types included by default and their use.
|
||||
|
||||
.. Tip::
|
||||
|
||||
When using lists, the `Multiple` (Y/N) keyword defines if there may be more than one item selected at a time.
|
||||
|
||||
.. Tip::
|
||||
|
||||
The xml keyword `Required` can be used to mark a field as being required.
|
||||
|
||||
ArrayField
|
||||
------------------------------------
|
||||
|
||||
The basic field type to describe a container of objects, such as a list of addresses.
|
||||
|
||||
.. Note::
|
||||
|
||||
This type can't be nested, only one level of ArrayField types is supported, you can use ModelRelationField to
|
||||
describe master-detail constructions.
|
||||
|
||||
|
||||
AuthGroupField
|
||||
------------------------------------
|
||||
|
||||
Returns and validates system (user) groups (found in :menuselection:`System --> Access --> Groups`)
|
||||
|
||||
|
||||
AuthenticationServerField
|
||||
------------------------------------
|
||||
|
||||
Select and validate authentication providers, maintained in :menuselection:`System --> Access --> Servers`.
|
||||
|
||||
|
||||
AutoNumberField
|
||||
------------------------------------
|
||||
|
||||
An integer sequence, which automatically increments on every new item of the same type in the same level.
|
||||
|
||||
BooleanField
|
||||
------------------------------------
|
||||
|
||||
Boolean field, where 0 means `false` and 1 is defined as `true`
|
||||
|
||||
CSVListField
|
||||
------------------------------------
|
||||
|
||||
List of (comma) separated values, which can be validated using a regex.
|
||||
|
||||
CertificateField
|
||||
------------------------------------
|
||||
|
||||
Option list with system certificates defined in :menuselection:`System --> Trust`, use the `Type` keyword to distinct between the
|
||||
available options (`ca`, `crl`, `cert`), defaults to `cert`.
|
||||
|
||||
ConfigdActionsField
|
||||
------------------------------------
|
||||
|
||||
Select available configd actions, supports filters to limit the number of choices. For example, the example below
|
||||
only shows actions which have a description.
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<command type="ConfigdActionsField">
|
||||
<filters>
|
||||
<description>/(.){1,255}/</description>
|
||||
</filters>
|
||||
</command>
|
||||
|
||||
|
||||
CountryField
|
||||
------------------------------------
|
||||
|
||||
Select and validate countries in the world.
|
||||
|
||||
EmailField
|
||||
------------------------------------
|
||||
|
||||
Validate if the input contains an email address.
|
||||
|
||||
HostnameField
|
||||
------------------------------------
|
||||
|
||||
Check if hostnames are valid (optionally allows IP addresses as well)
|
||||
|
||||
IntegerField
|
||||
------------------------------------
|
||||
|
||||
Validate if the input contains an integere value, optionally constrained by minimum and maximum values.
|
||||
|
||||
InterfaceField
|
||||
------------------------------------
|
||||
|
||||
Option list with interfaces defined in :menuselection:`Interfaces --> Assignments`, supports filters.
|
||||
The example below shows a list of non-dhcp active interfaces, for which multiple items may be selected, but at least one
|
||||
should be. It defaults to `lan`
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<interfaces type="InterfaceField">
|
||||
<Required>Y</Required>
|
||||
<multiple>Y</multiple>
|
||||
<default>lan</default>
|
||||
<filters>
|
||||
<enable>/^(?!0).*$/</enable>
|
||||
<ipaddr>/^((?!dhcp).)*$/</ipaddr>
|
||||
</filters>
|
||||
</interfaces>
|
||||
|
||||
|
||||
JsonKeyValueStoreField
|
||||
------------------------------------
|
||||
|
||||
A construct to validate against a json dataset retreived via configd, such as
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<program type="JsonKeyValueStoreField">
|
||||
<ConfigdPopulateAct>syslog list applications</ConfigdPopulateAct>
|
||||
<SourceFile>/tmp/syslog_applications.json</SourceFile>
|
||||
<ConfigdPopulateTTL>20</ConfigdPopulateTTL>
|
||||
<SortByValue>Y</SortByValue>
|
||||
</program>
|
||||
|
||||
|
||||
In which case `syslog list applications` is called to retrieved options, which is valid for 20 seconds (TTL) before fetching again.
|
||||
|
||||
|
||||
ModelRelationField
|
||||
------------------------------------
|
||||
|
||||
Define relations to other nodes in the model, such as to point the attribute `pipe` to a `pipe` node in the TrafficShaper model.
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<pipe type="ModelRelationField">
|
||||
<Model>
|
||||
<pipes>
|
||||
<source>OPNsense.TrafficShaper.TrafficShaper</source>
|
||||
<items>pipes.pipe</items>
|
||||
<display>description</display>
|
||||
</pipes>
|
||||
</Model>
|
||||
</pipe>
|
||||
|
||||
|
||||
|
||||
NetworkField
|
||||
------------------------------------
|
||||
|
||||
Validate if the value is a valid network address (IPv4, IPv6).
|
||||
|
||||
NumericField
|
||||
------------------------------------
|
||||
|
||||
Validate input to be of numeric type.
|
||||
|
||||
OptionField
|
||||
------------------------------------
|
||||
|
||||
Validate against a static list of options.
|
||||
|
||||
PortField
|
||||
------------------------------------
|
||||
|
||||
Check if the input contains a valid portnumber or (optionally) predefined service name. Can be a range when
|
||||
`EnableRanges` is set to `Y`.
|
||||
|
||||
TextField
|
||||
------------------------------------
|
||||
|
||||
Validate regular text using a regex.
|
||||
|
||||
UniqueIdField
|
||||
==================================
|
||||
|
||||
Generate unique id numbers.
|
||||
|
||||
UpdateOnlyTextField
|
||||
------------------------------------
|
||||
|
||||
Write only text fields, can be used to store passwords
|
||||
|
||||
UrlField
|
||||
------------------------------------
|
||||
|
||||
Validate if the input contains a valid URL.
|
@ -0,0 +1,21 @@
|
||||
----------
|
||||
Guidelines
|
||||
----------
|
||||
|
||||
.. rubric:: Some (simple) guidelines developing models
|
||||
:name: some-simple-guidelines-developing-models
|
||||
|
||||
#. One model should always be completely responsible for the its mount
|
||||
point, so if there's a model at mount point /A/B there can't be a
|
||||
model at /A/B/C
|
||||
#. Try to keep models logical and understandable, it's better to build
|
||||
two models for you application if the content of two parts aren't
|
||||
related to each other. It's no issue to create models at deeper
|
||||
levels of the structure.
|
||||
|
||||
#. When using more models in a application/module, you might want to
|
||||
consider the following naming convention: /Vendor/Module/Model
|
||||
|
||||
#. Try to avoid more disc i/o actions than necessary, only call save()
|
||||
if you actually want to save content, serializeToConfig just keeps
|
||||
the data in memory.
|
Loading…
Reference in New Issue