System settings

Description

The HTTP-based video interface provides the functionality for configuring system settings. This document describes the general syntaxes, requests and values that are used for general configurations of your Axis product.

The following CGIs are described in this document:

pwdgrp.cgiAdd, delete and manage user accounts.
factorydefault.cgiReload factory default. Some parameters are not set to their factory default value.
hardfactorydefault.cgiReload factory default. All parameters are set to their factory default value.
firmwareupgrade.cgiUpgrade the firmware version.
restart.cgiRestart the Axis product.
serverreport.cgiGet a server report from the Axis product.
systemlog.cgiGet system log information.
accesslog.cgiGet client log information.

Prerequisites

Identification

Property

Properties.API.HTTP.Version=3

Firmware

5.00 and later.

Add, modify and delete user accounts

The pwdgrp.cgi is used to add a new user account with password and group membership, modify the information and remove a user account.

Identification

Property

Properties.API.HTTP.Version=3

Firmware

5.00 and later

Access control

admin (Admin privileges are required if an admin user exists)

Method

GET/POST

//<servername>/axis-cgi/pwdgrp.cgi
<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

Argument Valid valuesDescription
action=<string>add
update
remove
get
add = Create a new user account.
update = Change user account information of specified parameters if the user account exists.
remove = Remove an existing user account.
get = Get a list of the user accounts which belong to each group defined.
user=<string>(1)A stringThe user account name (1-14 characters), a non-existing user account name. Valid characters are a-z, A-Z and 0-9.
pwd=<string>(1)A stringThe unencrypted password (1-64 characters) for the account. ASCII characters from character code 32 to 126 are valid.
grp=<string>(1)A stringAn existing primary group name of the account. The recommended value for this argument is users.
sgrp=<string> [:<string>...(1)]<string>[:<string>...]Colon separated existing secondary group names of the account. This argument sets the user access rights for the user account.

The recommended values for this group are:
viewer = Viewer access rights.
operator = Operator access rights.
admin = Admin access rights.
ptz = Access rights for PTZ control.


Please note that you should always give operator users both operator and viewer access rights, which means that both groups have to be specified. This also holds true for admin level users, who should have admin, operator and viewer access rights.

comment=<string>(1)A stringThe comment field of the account.
strict_pwd=<integer>An integerSet to 1 to enforce VAPIX® password standard. ASCII characters from characters 32 to 126 are valid.
  1. Required if action=add. Adding a value to comment is optional.

Example 1:

Create the initial admin user on the device, as it is not possible to log in to the device otherwise. The username and primary group must both be root, and all four secondary groups must be listed. This user can not be deleted and can only be created once.

Since logging in to the device is impossible at this stage, no authentication is required, but as soon as this user has been created, authentication and admin privileges are required for all user handling operations.

//<servername>/axis-cgi/pwdgrp.cgi?action=add&user=root&pwd=foo&grp=root&sgrp=admin:operator:viewer:ptz

Response

HTTP code

200 OK

Content-type

text/html

Created account root.

Example 2:

Create a new user account with viewer, operator, administrator and PTZ rights. The rights are set with the argument sgrp (secondary group).

//<servername>/axis-cgi/pwdgrp.cgi?action=add&user=joe&pwd=foo&grp=users&sgrp=viewer:operator:admin:ptz&comment=Joe

Response

HTTP code

200 OK

Content-type

text/html

Created account joe.

Example3:

Change the password of an existing account.

//<servername>/axis-cgi/pwdgrp.cgi?action=update&user=joe&pwd=bar

Response

HTTP code

200 OK

Content-type

text/html

Modified account joe.

Example 4:

Remove an account.

//<servername>/axis-cgi/pwdgrp.cgi?action=remove&user=joe

Response

HTTP code

200 OK

Content-type

text/html

Removed account joe.

Example 5:

List groups and users. In this example Joe is the administrator, Ellen is the operator with PTZ rights and Frank is the viewer without PTZ rights.

The digusers parameter lists all created users . Also, admin, operator, viewer and ptz are access group rights, meaning that Joe, who is the administrator, will be listed in all groups, while Ellen is only visible in operator, viewer and ptz, as her account only has the access rights to these. The remaining user groups are system-only, meaning they only exist internally on your Axis device.

//<servername>/axis-cgi/pwdgrp.cgi?action=get

Response:

HTTP code

200 OK

Content-type

text/plain

root="root"
daemon="root,bin,daemon"
bin="root,bin,daemon"
sys="root,bin"
adm=""
tty="scheduled,imaged,ptzadm"
disk="actionengined,streamer,tampering,motion,optics,imaged,ptzadm,focus,light"
lp="daemon"
mail=""
news=""
uucp=""
man=""
proxy=""
kmem=""
input=""
dialout=""
fax=""
voice=""
cdrom=""
floppy=""
tape=""
sudo=""
audio="streamer,mediaclip,audiocontrol,mediaclipcgi,audio-equalizer,sdk"
dip=""
www-data=""
backup=""
list=""
irc=""
src=""
gnats=""
shadow="www,streamer"
utmp="streamer"
video="ptod,remote-syslogd,viewarea,light,video-scene-provider,vdn,sdk,inertiald,wwwaovp,focus,streamer,optics,larod,tampering,mord,xved,imaged,rotation,lens_correctiond,video-object-detection,maskd,ptzadm,motion,posd,vdo,overlay,videoapi"
sasl=""
plugdev=""
kvm=""
staff=""
games=""
shutdown=""
users="frank,joe,ellen"
admin="wwwaop,wwwaov,wwwap,wwwav,wwwa,wwwao,sdk,wwwaovp,root,joe,wwwavp"
operator="ellen,wwwovp,wwwaop,wwwaov,wwwop,wwwo,wwwao,wwwov,sdk,wwwaovp,root,joe,ptzadm"
viewer="wwwv,joe,root,frank,sdk,wwwovp,wwwaovp,wwwavp,wwwvp,wwwaov,wwwov,ellen,wwwav"
ptz="wwwp,joe,root,wwwovp,wwwaovp,wwwavp,wwwaop,wwwvp,wwwop,wwwap,ellen"
anonymous="anonymous"
template="environment,ptzadm"
crypto="www,stclient"
gpio="actionengined,streamer,posd,iod,led,vdo,imaged,environment,scheduled,focus,light,ptzadm"
tpm="wwwaovp,www,streamer,mqtt-client,stclient"
compute="larod"
videohw="vdo,xved,imaged"
www="storage"
messagebus="messagebus"
focus=""
buzzer="focus"
sdk="sdk"
wsd="scheduled,wsdd"
sessioncgi="sessioncgi"
pwauth="www"
streamer="www,storage,sdk"
event="event,actionengined,streamer"
storage="wwwaovp,actionengined,streamer,sdk,wsd"
wsauth="scheduled,streamer,wsd"
actionengined="wwwaovp"
iiodevices="posd,actionengined,ptzadm"
stclient=""
sshd=""
upnp="upnp"
rendezvous="rendezvous"
led="led"
ptod="ptod"
environment="environment"
virtualinputd="virtualinputd"
depd="depd"
eventbridged="eventbridged"
scheduled=""
imaged="maskd"
motion="motion"
tampering=""
ptzadm="sdk"
wsdd="wsdd"
systemd-journal="systemlog"
iod="iod"
maskd="maskd"
gtourd="gtourd"
light=""
power="power"
snmpd=""
confcached=""
posd=""
ruleengined=""
metadata="streamer"
audioapi=""
videoapi=""
tracing=""
legacymappings="led,audiocontrol,iod,mediaclip,videoapi,imaged,ptzadm,maskd"
systemd-bus-proxy=""
confloggerd="confloggerd"
netd=""
service_registry="mediaclip,iod,audiocontrol,ptzadm"
addon="atf-tester,axis-tester,atf-architecture-all"
vdo=""
overlay="vdo,videostreamingindicator,dynamic_overlayd,maskd,streamer"
gpu="overlay,larod,sdk,mord"
lldpd=""
eventproducerd="eventproducerd"
eventconsumerd="eventconsumerd"
dynamic_overlayd=""
capturemoded=""
vdn=""
audio-site=""
product-info=""
geolocationd="geolocationd"
systemmanager=""
diskmanager=""
ntp=""
storage-stability-helper="storage-stability-helper"
addonmanagerconf="addonmanagerconf"
video-service-legacy=""
licensekey-manager="licensekey-manager"
httpwdd="httpwdd"
ntpconfd=""
basic-device-info=""
mord=""
optics="actionengined,imaged,light"
audiocontrol=""
netservicesd=""
addonexample="addonexample"
onscreencontrols=""
systemlog=""
api-discovery=""
video-object-detection=""
larod=""
videostreamingindicator=""
time-service=""
xved=""
device-monitor=""
viewarea=""
mediaclip="mediaclip"
inertiald="inertiald"
mqtt-client="wwwaovp,actionengined"
remote-syslogd="remote-syslogd"
mdns-sd-confd=""
ssh-confd=""
rotation=""
audio-equalizer=""
streamcontrol=""
video-scene-provider=""
larod-users="mord"
qca8337="actionengined,netd"
metadata-receiver=""
audiomixer=""
nogroup=""
digusers="root,joe,ellen,frank"

Example 6:

Create an account with enforced VAPIX® password standards. 

//<servername>/axis-cgi/pwdgrp.cgi?action=add&user=joe&pwd=foo&grp=users&sgrp=viewer:operator:admin:ptz&comment=Joe&strict_pwd=1

Response

HTTP code

200 OK

Content-type

text/html

Modified the account joe.

Error Responses:

Example 7:

HTTP code

200 OK

Content-type

text/html

Error: consult the system log file.

Example 8:

If the action is omitted or is not one of "add", "update", "remove" or "get".

HTTP code

200 OK

Content-type

text/html

Error: action operation type.

Example 9:

No user name supplied, or the user name contains characters other than A-Z, a-z or 0-9.

HTTP code

200 OK

Content-type

text/html

Error: account user name.

Example 10:

The user name is not appropriate for the action.

HTTP code

200 OK

Content-type

text/html

Error: malformed action operation, <action>.

Example 11:

No admin user has been created and the user that tried to be added is not a valid initial admin user.

HTTP code

200 OK/401 Unauthorized

Content-type

text/html

Error: not a valid initial admin user.

Example 12:

No admin user has been created. Start by creating one and use it to login and perform the requested operation.

HTTP code

200 OK/401 Unauthorized

Content-type

text/html

Error: initial admin user must be created first.

Example 13:

Only root can modify itself.

HTTP code

200 OK

Content-type

text/html

The root account may only be modified by root.

Factory default

Note
See factoryDefault in the Firmware management API for updated information.

The factorydefault.cgi is used to reset to factory default. All settings are set to their factory default values except.

  • The boot protocol (Network.BootProto).

  • The static IP address (Network.IPAddress).

  • The default router (Network.DefaultRouter).

  • The subnet mask (Network.SubnetMask).

  • The broadcast IP address (Network.Broadcast).

  • The system time.

  • The IEEE 802.1X settings.

Since these parameters are not reset the Axis product can be accessed on the same address. This is especially important when using NAT router. After the Axis product has been reset to factory default it is restarted as part of this function.

Access control

admin

Method

GET

Syntax:
//<servername>/axis-cgi/factorydefault.cgi

Response:

HTTP code

200 OK

Content-type

text/html

<html response>

Hard factory default

Note
See factoryDefault in the Firmware management API for updated information.

The hardfactorydefault.cgi is used to reset to factory default. All settings, including the IP addresses, are set to their factory default values. After the Axis product has been reset to factory default it is restarted as part of this function.

Access control

admin

Method

GET

Syntax:
//<servername>/axis-cgi/hardfactorydefault.cgi

Response:

HTTP code

200 OK

Content-type

text/html

<html response>

Firmware upgrade

Note
See Upgrade in the Firmware management API for updated information.

The firmwareupgrade.cgi is used to upgrade the firmware version. After the Axis product has been upgraded with a new firmware it is restarted as part of this function.

Access control

admin

Method

POST

Syntax:
//<servername>/axis-cgi/firmwareupgrade.cgi[?<argument>=<value>]

With the following arguments and values:

ArgumentValid valuesDescription
type=<string>normal
factorydefault
Specifies the type of firmware upgrade.

normal = Upgrade and restore old settings.
factorydefault = All parameters are set to their default value.

Default: normal.

The file content is provided in the HTTP body according to the format given in RFC 1867. The body is created automatically by the browser if using HTML form with input type "file".

Body:
POST /axis-cgi/firmwareupgrade.cgi?type=normal HTTP/1.0
Content-Type: multipart/form-data; boundary=<boundary>
Content-Length: <content length>
 
--<boundary>
Content-Disposition: form-data; name=<name>;
filename="<file name>"
Content-Type: application/octet-stream
 
<firmware file content>
 
--<boundary>

For more Firmware upgrade options, see Firmware management API

Restart server

Note
See Reboot in the Firmware management API for updated information.

The restart.cgi is used to restart the Axis product.

Access control

admin

Method

GET

Syntax:
//<servername>/axis-cgi/restart.cgi

Response:

HTTP code

200 OK

Content-type

text/html

<html response>

Server report

Description

The serverreport.cgi is used to generate and return a server report. This report is useful as an input when requesting support. The report includes product information, parameter settings and system logs.

HTTP API

Access control

Admin

Method

GET/POST

//<servername>/axis-cgi/serverreport.cgi[?<argument>=<value>]
ParameterValid valueDescription
mode=<string>text
zip
zip_with_image(1)
The server report presentation mode.
text will return the server report as text.
zip will return the server report as a .zip-file.
zip_with_image will return report together with a snapshot image taken using the Image Appearance settings as a single .zip-file.
Optional. If mode is not specified, the value defaults to text.
  1. Only available on products with application support.

Common examples

Example 1: Get the server report as text

//<servername>/axis-cgi/serverreport.cgi?mode=text

Response

HTTP code

200 OK

Content-type

text/plain

<server report>

Example 2: Get the server report as a .zip-file

//<servername>/axis-cgi/serverreport.cgi?mode=zip

Response

HTTP code

200 OK

Content-type

application/zip

<.zip-file>

Example 3: Get the server report and a snapshot image with the current image settings as a .zip-archive

//<servername>/axis-cgi/serverreport.cgi?mode=zip_with_image

Response

HTTP code

200 OK

Content-type

application/zip

<message>

Logs

Parameters

Log.Access

These parameters control inclusion of information in the client access log.

Note
Parameter Log.Access is not available in firmware 5.60 and later.
Log.Access
ParameterDefault valuesValid valuesAccess controlDescription
MaxSize400001000 ... 100000admin: read, writeThe maximum size of the access log.
Criticaldetailedoff
on
detailed
admin: read, writeSet the level of critical messages that should be shown in the access log.
Warningdetailedoff
on
detailed
admin: read, writeSet the level of warning messages that should be shown in the access log.

off = No warning messages will be shown.
on = All suspected intrusions are shown.
detailed = All suspected intrusions and access denied events are shown.
Informationaloffoff
on
detailed
admin: read, writeSet the level of informational messages that should be shown in the access log.

off = No informational messages will be shown.
on = Most access information will be shown, but some similar and trivial messages are filtered out.
detailed = All information will be shown.

Log.System

These parameters control inclusion of information in the system log.

Note
Parameter Log.System is not available in firmware 5.60 and later.
Log.System
ParameterDefault valuesValid valuesAccess controlDescription
MaxSize400001000 ... 100000admin: read, writeThe maximum size of the system log.
Criticaldetailedoff
on
detailed
admin: read, writeSet the level of critical messages that should be shown in the system log.

off = No critical messages will be shown.
on = All critical messages will be shown.
detailed = All critical messages will be shown.

Note: Today there is no difference setting the level to on or detailed.
Warningdetailedoff
on
detailed
admin: read, writeSet the level of warning messages that should be shown in the system log.

off = No warning messages will be shown.
on = All warning messages will be shown.
detailed = All warning messages will be shown.

Note: Today there is no difference setting the level to on or detailed.
Informationaloffoff
on
detailed
admin: read, writeSet the level of informational messages that should be shown in the system log.

off = No informational messages will be shown.
on = All informational messages will be shown.
detailed = All informational messages will be shown.

Note: Today there is no difference setting the level to on or detailed.

MailLogd

Parameters for log levels to send as e-mail.

MailLogd
ParameterDefault valuesValid valuesAccess controlDescription
LogSendLevel00 ... 3admin: read, writeMessage that are sent in e-mail:

0 = None.
1 = Critical.
2 = Critical and Warning.
3 = Critical, Warning and Information.
ToEmail<string>admin: read, writeThe e-mail address to where log messages are sent.

HTTP API

System log

The systemlog.cgi is used to retrieve system log information. The level of information included in the log is set in the Log.System parameter group.

Access control

admin

Method

GET

Syntax:
//<servername>/axis-cgi/systemlog.cgi

Response:

HTTP code

200 OK

Content-type

text/plain

Body:
<system log information>

Access log

The accesslog.cgi is used to retrieve client access log information. The level of information included in the log is set in the Log.Access parameter group.

Access control

admin

Method

GET

Syntax:
//<servername>/axis-cgi/accesslog.cgi

Response

HTTP code

200 OK

Content-type

text/plain

Body:
<access log information>

System date and time

Note
This API will no longer receive updates. For a newer version on how to configure date, time and time zones, see Time API.

Get or set the system date and time.

Parameters

Time

The parameters in the time group control the common time information for the time zone, how date and time are synchronized and the offset related to the chosen time zone and Coordinated Universal Time, UTC.

Time
ParameterDefault valuesValid valuesAccess controlDescription
ObtainFromDHCPyesyes
no
admin: read, writeDHCP servers may provide names/IP addresses for local/remote NTP servers. Enable this feature by setting this parameter to yes.
SyncSourceProduct/release dependent.PC
NTP
None(1)
admin: read, writeThe source to synchronize the time with.

PC = Synchronize the time with the connected PC.
NTP = Synchronize the time with a NTP server.
None = Set the time manually.
POSIXTimeZoneGMT0BST,M3.5.0/1,M10.5.0<name><offset>[<dst name>[dst offset>[,<start rule>,<stop rule>]]](2)

The ':' prefixed format is not allowed.

admin: read, write
operator: read
This parameter specifies the time zone with and/or without DST. See section Time zone below for more information.
  1. Product/release dependent. Check the product’s release notes.
  2. POSIX TZ rule strings as defined for the TZ variable in Chapter 8.3, The Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004.

Set the TimeZone.

//myserver/axis-cgi/param.cgi?action=update&Time.POSIXTimeZone=GMT0BST,M3.5.0/1,M10.5.0

This timezone, standard time named GMT and daylight saving time named BST, has daylight saving time. The standard local time is GMT. Daylight saving time, 1 hour ahead of GMT, starts the last Sunday in March at 01:00 and ends the last Sunday in October at 02:00.

Time.DST

The parameter in the Time.DST group controls the Daylight Saving Time (DST).

Time.DST
ParameterDefault valuesValid valuesAccess controlDescription
Enablednoyes
no
admin: readEnable/disable DST.

yes = Enable DST.
no = Disable DST.

Time zone

POSIXTimeZone specifies the time zone with or without DST. The value is added according to the following syntax:

<name><offset>[<dst name>[dst offset>[,<start rule>,<stop rule>]]]

<name> and <dst name> = The name of the time zone without and with DST. A name is at least 3 characters long and at most 6 characters long. It can be unquoted or quoted. An unqouted name may only contain the characters A-Z and a-z. A quoted name starts with the < character and ends with a > character. It can have the characters A-Z, a-z, 0-9, - and +.

<offset> and <dst offset> = The offset for the time zone and the daylight saving time, respectively. An offset specifies the amount of time that when added to the local time is equal to UTC. For example the offset for Paris, France, without daylight saving time, is -1 and the offset for Chicago, Ill., without daylight saving time, is +6. Offsets are specified as HH:MM:SS (hours, 0-24; minutes 0-59 and seconds 0-59) preceded by '-' indicating a negative offset or an optional '+', indicating a positive offset. Minutes and seconds are optional, thus the valid formats are "HH" "HH:MM" "HH:MM:SS". The dst offset may be omitted and will then default to one hour ahead of the zone's standard time.

<start rule> and <stop rule> = The daylight saving time start and stop rules are specified in the form date or date/time. The date is specified in the form Month.Week.Day, Jday, or day. The Month.Week.Day form sets the month (1-12), week (1-5, with 5 meaning the last week in Month that Day occurs) and day (0-6, 0 is Sunday). The Jn form sets the n:th day (1-365, leap days are not counted). The n form sets the day (0-365, leap days are counted; day 365 thus only exists in leap years).

The time is specified as HH, HH:MM or HH:MM:SS, as the offsets above. It is the local time for the DST transition. The time is always positive and must not be preceded by a sign. If the time is omitted the daylight saving time transition occurs at 02:00:00.

Example: If a zone has a 1 hour DST to standard time offset and the transition time to DST is 02:00 then 01:59:59 will be followed by 03:00:00. If the transition time from DST to standard time in the same zone is 02:00 then 01:59:59 (daylight saving time) will be followed by 01:00:00 (standard time).

Time.NTP

The parameters in the Time.NTP set time and date with the NTP protocol.

Time.NTP
ParameterDefault valuesValid valuesAccess controlDescription
Server0.0.0.0An IP address or a host name.admin: read, writeThe NTP server to connect to when synchronizing the time in the Axis product.
VolatileServerAn IP address or a host name.admin: readThe name/IP address of the NTP server, received from the DHCP server. Only one NTP server is currently supported. The NTP server name/IP address will be valid only until the next DHCP renewal or reboot.