Creating Models / 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/ 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 System ‣ Access ‣ Groups)

AuthGroupField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

AuthenticationServerField

Select and validate authentication providers, maintained in System ‣ Access ‣ Servers.

AuthenticationServerField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Filters

Y,N

A structure of regex filters per atribute to exclude certain options from the list

AutoNumberField

An integer sequence, which automatically increments on every new item of the same type in the same level.

AutoNumberField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

MinimumValue

int

Minimum number also starting point of the sequence

MaximumValue

int

Maximum number

Base64Field

Validate if a given string contains a valid base64 decodable value.

Base64Field

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

Mask

regex

Optional validation regex

BooleanField

Boolean field, where 0 means false and 1 is defined as true

BooleanField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

CertificateField

Option list with system certificates defined in System ‣ Trust.

CertificateField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Type

ca, crl, cert

Type of certificate to select, defaults to cert

CSVListField

List of (comma) separated values, which can be validated using a regex.

CSVListField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

Mask

regex

Optional validation regex

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.

<command type="ConfigdActionsField">
    <filters>
        <description>/(.){1,255}/</description>
    </filters>
</command>
ConfigdActionsField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Filters

Y,N

A structure of regex filters per atribute to exclude certain options from the list

CountryField

Select and validate countries in the world.

CountryField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

AddInverted

Y,N

Add ‘inverted’/excluded countries to the list, copies contry codes prefixes an ! (e.g. !NL)

EmailField

Validate if the input contains an email address.

EmailField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

HostnameField

Check if hostnames are valid, includes the following options:

HostnameField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

IpAllowed

Y,N

Allow an ip address

HostWildcardAllowed

Y,N

Allow * for all hostnames

FqdnWildcardAllowed

Y,N

Allow partial wildcard for fully qualified domain names (e.g. *.my.top.level.domain)

ZoneRootAllowed

Y,N

Allow the zone root marker (@)

IntegerField

Validate if the input contains an integere value, optionally constrained by minimum and maximum values.

EmailField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

MinimumValue

int

Minimum number

MaximumValue

int

Maximum number

InterfaceField

Option list with interfaces defined in 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

InterfaceField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Filters

Y,N

A structure of regex filters per atribute to exclude certain options from the list

AddParentDevices

Y,N

Add parent devices in the list when not assigned

AllowDynamic

Y,N,S

Allow dynamic (hotplug) interfaces, when set to S hotplug interfaces without a static address are ignored

<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

<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.

JsonKeyValueStoreField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

ConfigdPopulateAct

text

Configd command responsible for the data

SourceFile

text

Temporary filename where results are stored

ConfigdPopulateTTL

int

Time To Live in seconds

SortByValue

Y,N

Sort by value, default sorts by key

LegacyLinkField

Read-only pointer to legacy config data, reads (single) property from the legacy configuration and returns its content when it exists (null if xml item doesn’t exist).

The following example would read the enabled property from the config xml, which resides in <ipsec><enabled>1</enabled></ipsec>

<enabled type="LegacyLinkField">
    <Source>ipsec.enable</Source>
</enabled>

Note

Values stored into this fieldtype will be discarded without further notice, which practically means the target structure will always contain an empty field as long as its used as a pointer. When functionality migrates to mvc, you can switch the type and supply migration code to load the initial values.

ModelRelationField

Define relations to other nodes in the model, such as to point the attribute pipe to a pipe node in the TrafficShaper model.

<pipe type="ModelRelationField">
    <Model>
        <pipes>
            <source>OPNsense.TrafficShaper.TrafficShaper</source>
            <items>pipes.pipe</items>
            <display>description</display>
        </pipes>
    </Model>
</pipe>
ModelRelationField

Parameter

Options

Purpose

default

text

Default value for new attributes

display

text

Comma separated list of fields to display

display_format

text

vsprintf() format string

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Model

xml

structure as described in the sample above

NetworkAliasField

Validate if the value is a valid network address (IPv4, IPv6), special net or alias. Predefined special networks contain the following choices:

  • any
    • any network

  • (self)
    • This firewall

  • [interface]
    • Interface network, where interface is one of lan, wan, opt[XX] (e.g. opt1, opt2)

  • [interface]ip
    • Interface address

All network/host type aliases (including, but not limited to GeoIP) defined in Firewall -> Aliases are also valid choices.

NetworkAliasField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

NetworkField

Validate if the value is a valid network address (IPv4, IPv6).

NetworkField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

Mask

regex

Optional validation regex

NetMaskRequired

Y,N

Is a netmask required

NetMaskAllowed

Y,N

Is a netmask allowed

AddressFamily

ipv4, ipv6

Which address family to use, blank means ipv4+ipv6

FieldSeparator

text

Separator character to use

WildcardEnabled

Y,N

Allow the use of the any clause

AsList

Y,N

Field type should return list items

NumericField

Validate input to be of numeric type.

NumericField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

MinimumValue

int

Minimum number

MaximumValue

int

Maximum number

OptionField

Validate against a static list of options.

OptionField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

OptionValues

xml

Xml structure containing keys and values, when keys should be numeric, the value tag is also supported <opt1 value='1'>option1</opt1>

PortField

Check if the input contains a valid portnumber or (optionally) predefined service name. Can be a range when EnableRanges is set to Y.

PortField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options, when set the type is treated as a list

EnableWellKnown

Y,N

Allow the usage of well known names such as ‘http’ and ‘ssh’

EnableRanges

Y,N

Allow the usa of ranges, such as 80:100

ProtocolField

List field type to validate if the provided value is a valid protocol name as defined by /etc/protocols (e.g. TCP, UDP) extended with the any option.

ProtocolField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

TextField

Validate regular text using a regex.

TextField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

Mask

regex

Optional validation regex

UniqueIdField

Generate unique id numbers.

UniqueIdField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

UpdateOnlyTextField

Write only text fields, can be used to store passwords

TextField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

Mask

regex

Optional validation regex

UrlField

Validate if the input contains a valid URL.

UrlField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

VirtualIPField

Select a virtual address defined in Interfaces -> Virtual IPs -> Settings, use with a bit of care as the keys (addresses) are subjected to change.

VirtualIPField

Parameter

Options

Purpose

default

text

Default value for new attributes

Required

Y,N

Mark field as required

ValidationMessage

text

Error message on validation failure

BlankDesc

text

Set a label for the empty option

Multiple

Y,N

Allow to select multiple options

Type

text

The virtual ip type to select, * for all (default)