Bulk import & export

Five kinds of object can leave Taranac as a file and come back from one: devices, device groups, network objects, users and user groups. Use it to onboard a few hundred switches from an inventory spreadsheet, to change one field on every device at once, or to carry master data from a lab to production.

An import is not a shortcut around the forms. Every row goes through the same service the form uses, with the same validation, the same permission guards, the same secret handling and the same audit events. A row the form would refuse is refused, and only that row: the others import. A preview runs the real import and rolls it back, so what it shows is what the import will do.

This page covers the formats, the export, the import walkthrough and its modes, the rules a file follows (the row contract), secrets, permissions, the columns of each entity, and how errors and the audit trail look.

Entity	Where	A row is matched by	Notes
Devices	Infrastructure → Network → Devices	Name (exact)	The address names a network object, which is reused or created.
Device groups	Infrastructure → Network → Device Groups	Name (exact)	The Members column is the group’s whole device list.
Network objects	Infrastructure → Network → Network Objects	Name (exact)	All four entry types: host, subnet, range, FQDN.
Users	Infrastructure → Identity → Users	Username (ignoring case)	Local users only. Passwords go in, never out.
Groups	Infrastructure → Identity → Groups	Name (exact)	Local groups only. The Members column is the whole member list.

Each list has an Export and an Import button above the table. An import never deletes anything: an object missing from the file stays as it is.

Format	Export	Import	Notes
XLSX	Yes (the UI’s default)	Yes	One Data sheet with a styled header row and a note on every header cell. On import the Data sheet is read, or the first sheet when there is none. Legacy .xls is refused: save it as Excel Workbook (.xlsx).
CSV	Yes, UTF-8 with BOM, comma-separated	Yes	Must be UTF-8 (with or without BOM). The delimiter is read from the header line: ,, ; or tab, so a CSV saved by Excel in a locale that uses ; imports as is.
JSON	Yes	Yes	An object with a data list of row objects, plus a meta block on export (entity, time, count, whether secrets were included). The API’s default format.

The template (Download Template in the import drawer) is always XLSX. It has the import columns and no data rows. Each header cell’s note says whether the column is required, what it means and gives an example value. A Reference sheet lists the names the file may use: device groups, collectors, SNMP profiles and vendor dictionary keys for devices; devices and SNMP profiles for device groups; entry types for network objects; local groups, languages, enable modes and yes/no words for users; RBAC models, local users, web-login modes and enable modes for groups.

An exported file is a valid import file. The export writes every column except the import-only ones (a user’s password), and the template offers every column except the export-only ones (a device’s network object name, a user’s or group’s source). Headers are always English. The notes follow the language you use the console in.

Click Export above the list. Choose:

• Format — XLSX, CSV or JSON.
• Scope — every object of that kind, or only the rows you selected in the table.
• Include secrets (devices and device groups only) — see Secrets.

The export is sorted by name. Every export is audited as DATA_EXPORTED, with the entity, the format, the row count and whether secrets were included.

1. Click Import above the list. The button is shown only to a role with <entity>.create.
2. Start from an export of the same list, or from Download Template. Edit the rows you want to create or change. Delete the columns you do not want to touch (see The row contract).
3. Drop the file into the drawer (.xlsx, .csv or .json; anything else is refused before upload).
4. Pick the Conflict Resolution mode (below).
5. Turn on Dry run and click Preview. The import runs in full and is rolled back. The result shows the counts (total, created, updated, skipped, errors), notices about the file, and one line per row with its status and message.
6. If the preview has no errors and something to create or update, Import now runs the same file in the same mode. Otherwise fix the file, go Back, and preview again.

Without Dry run the Import button writes straight away. Rows without errors are saved; rows with errors are not. Fix those rows and import the file again: in Create only mode the rows already created are skipped.

Mode	An object with the row’s name exists	No such object	Extra permission
Create only (default)	Row skipped	Created	—
Update existing	Updated, only in the columns the file has	Created	<entity>.edit (the mode is greyed out without it)
Fail on conflict	Row error: Object ”…” already exists	Created	—

Fail on conflict refuses the row, not the file: the other rows still import. Preview first if you want to know before anything is written.

The file says exactly what to change, and nothing else. A partial file — two columns, or ten rows — changes only what it contains.

In the file	On a new object	On an existing object (Update existing)
Column absent	The form’s default	Left untouched
Cell filled	Set	Set
Cell empty, field that can be empty	Left empty	Cleared: back to inherit for a secret, banner, CoA port or SNMP profile; [] for a list
Cell empty, field that cannot be empty (a name, a yes/no column, a required column)	Row error: Column ”…” cannot be empty	Same row error
A list column (groups, members)	The listed set	The whole set: names not listed are removed, an empty cell removes them all
A name that matches nothing (a group, member, collector, SNMP profile, RBAC model)	Row error: Column ”…”: not found: …	Same row error — never silently dropped

Two columns step outside the “empty clears” rule because there is nothing to clear: a user’s Password cell left empty keeps the current password, and a secret cell holding the mask •••••••• keeps the stored secret.

Each row runs on its own. A row refused by validation, a permission guard or the database is rolled back whole — it never leaves half its writes behind — and reported with its reason. Every name a row refers to is resolved before anything is written.

• Headers are matched ignoring case and extra spaces. The column’s internal key works too (protocol_tacacs for TACACS+ Enabled). An unknown column is ignored with a notice; a column repeated is read once, with a notice.
• Yes/no columns take true/false, yes/no, y/n, 1/0, on/off, the same words in every language the console ships, and the TRUE/FALSE a localized Excel writes into a CSV. Anything else is a row error, never a quiet “no”.
• Lists (tags, groups, members) are comma-separated, or a JSON array.
• Dates (a user’s validity) are a date cell or ISO 8601 such as 2026-01-01T00:00:00Z. A value without a time zone is taken as UTC.
• Numbers in text columns stay text as typed: a Location of 7604 is 7604, not 7604.0.
• Secrets and passwords are read exactly as typed, spaces included: " pass " is a different secret from "pass".
• Blank lines are skipped.
• Row numbers in the result are spreadsheet rows (the header is row 1). For JSON they are the item’s position in the data list.

Device and device-group exports leave the TACACS+ Key, RADIUS Secret and CoA Secret columns out unless you tick Include secrets. That option is offered only to a role with devices.edit (or device_groups.edit), the same right that reveals a secret in the form. The API refuses include_secrets to anyone else. The file then holds the secrets in plain text; handle it like the secrets themselves. The DATA_EXPORTED entry records that secrets were included. The option is never remembered between exports.

On import, a secret cell means:

Cell	Meaning
A value	Set that secret
Empty	Clear it: the object goes back to inheriting (device → group → global)
•••••••• (eight bullets, the mask the console shows for a stored secret)	Keep the stored secret. On a new object there is nothing to keep, so nothing is set

Users and groups are exported without their Enable Password, so an exported users file re-imports without touching it. On import the column works like a device secret: a value sets it, •••••••• keeps it and an empty cell clears it. Enable Mode custom needs an enable password on a new user or group.

User passwords and password hashes never leave Taranac in a file. The NT hash that PEAP/MSCHAPv2 needs is password-equivalent, so it is never exported, and the hash alone would arrive without it. To move users, restore a backup, whose archive carries the hashes encrypted, or import them with a temporary password or rely on the welcome email.

Text in a spreadsheet that begins with =, +, - or @ is run as a formula when the file is opened. Device descriptions, names and tags are typed by people, so exports write such values as text: in XLSX as a text cell with Excel’s own quote prefix, in CSV with a leading '. Importing the file back strips exactly that prefix, so a value of -core- round-trips unchanged, and a value that merely begins with ' is kept as it is. The AAA, NAC and audit log exports are formula-safe too.

Import and export borrow the permissions of the entity they work on; there is no separate import permission.

Action	Needs
Export, download the template	<entity>.view
Export with secrets (devices, device groups)	<entity>.edit as well
Import (Create only, Fail on conflict)	<entity>.create
Import in Update existing mode	<entity>.edit as well
A Members column (groups, device groups)	manage_members on that section
Device SNMP Enabled / SNMP Profile, device group SNMP Profile	snmp.edit

<entity> is devices, device_groups, network_objects, users or groups. A guarded column counts when the file would write it: in Update existing mode even an empty cell clears the field, so the column alone needs the permission; in the other modes only a filled cell does. Without the permission the whole import is refused before any row runs. The drawer warns about a membership column your role cannot write.

On top of that, every row meets the guards of the form: only an administrator may change an administrator, set a group’s admin flag, RBAC model or web-login mode, or set a password for a member of an admin group; and no one may grant a group or role richer than their own (see Who may change whom). Such a row is refused with the form’s message.

Bold columns are required for a new object. Columns marked export only are written by an export and ignored on import.

Column	What it carries
Name	Unique device name; rows are matched by it.
Hostname	DNS host name.
Address	An IP address or CIDR. An existing host or subnet network object with that value is used — unless another device holds it, which is a row error. Otherwise a network object is created, named after the device, or after the address when the device’s name is taken by another object. When both names are taken the row is refused rather than given an invented third name. A host is exported without /32.
Network Object	Export only: the name of the device’s network object.
Description, Location, Notes	Free text.
TACACS+ Key, RADIUS Secret	Secrets — see Secrets. Empty = inherit.
TACACS+ Enabled, RADIUS Enabled, NAC Enabled	Yes/no. A new device without these columns gets TACACS+ and RADIUS on, NAC off. A file with only some of them leaves the others as they are.
Vendor, Platform, Model, Serial Number, OS Version	Device facts. A value from a file counts as typed by hand, so an SNMP poll does not overwrite it. Empty clears it, and SNMP may fill it again.
Vendor Dictionary	Key of a NAC vendor dictionary entry, used for CoA. Empty = detect automatically.
Tags	Comma-separated or a JSON array.
Single Connection	Yes/no (TACACS+ single-connection mode).
Enabled	Yes/no. A disabled device is left out of the daemon configuration.
CoA Port	1–65535. Empty = inherit.
CoA Secret	Secret. Empty = inherit.
Welcome Banner, MOTD Banner	TACACS+ login banners. Empty = inherit.
Collector	Name of the configuration-tracker collector that reaches the device. Empty = none.
SNMP Enabled	Yes/no: poll the device over SNMP. Only a single-host address can be polled. A row that turns polling off and moves the device to a subnet is accepted; one that only moves a polled device to a subnet is refused, as in the form.
SNMP Profile	Name of an SNMP profile. Empty = inherit.
Groups	Device group names: the device’s whole membership.

Field meanings and inheritance are on Network devices and SNMP.

Column	What it carries
Name	Unique group name; rows are matched by it.
Description, Tags	As on devices.
TACACS+ Key, RADIUS Secret, CoA Secret	Secrets. Empty = inherit from the global setting.
CoA Port	1–65535. Empty = inherit.
Welcome Banner, MOTD Banner	Empty = inherit.
SNMP Profile	Name of an SNMP profile. Empty = inherit.
Members	Device names: the group’s whole membership. Devices not listed leave the group; an empty cell empties it. Each device joining or leaving is audited, as from the group’s member list.

Column	What it carries
Name	Unique name; rows are matched by it.
Description, Tags	Free text; tags comma-separated or a JSON array.
Entry Type	host, subnet, range or fqdn. Fixed once the object exists: a file may repeat it, not change it. To change it, delete the object and import it again.
Network	For host an IP address, for subnet a CIDR.
Range Start, Range End	For range: the first and last address, same IP version, start not after end.
FQDN	For fqdn: a host name such as radius.example.com.

A value column that does not belong to the row’s entry type must be empty. The entry type’s own columns are required on a new object and cannot be emptied on an existing one. Two objects with the same value are refused, as in the form.

Column	What it carries
Username	Up to 64 characters; matched to existing local users ignoring case.
Email	Email address.
First Name, Last Name, Display Name, Phone	Empty clears. An empty Display Name shows the first and last name.
Password	Import only. Required for a new user and checked against the password policy. On an existing user a value sets a new password; an empty cell keeps the current one.
Active	Yes/no. A new user is active when the file has no such column.
Must Change Password	Yes/no: ask for a new password at the next login.
Language	An interface language code from the Reference sheet. A new user without it gets the system default language.
Groups	Group names: the user’s whole group list.
Valid From, Valid Until	Date or ISO 8601, UTC when no zone is given. Valid Until must be later than Valid From. Empty removes the limit.
Enable Mode	inherit, login_password, custom or deny.
Enable Password	For custom. Not exported — see Secrets.
Auth Source	Export only: always local.

Column	What it carries
Name	Unique group name; rows are matched by it.
Description	Empty clears.
Admin Group	Yes/no: members get full administrator access. Only an administrator can change it.
MFA Required	Yes/no.
Web Login	inherit, allow or deny. Only an administrator can set allow or deny; an administrator group cannot deny.
RBAC Model	Name of an RBAC model. Empty unbinds it. Only an administrator can change it.
Members	Usernames: the group’s whole member list. Each member added or removed is audited.
Enable Mode, Enable Password	As on users.
Source	Export only: always local.

Field meanings are on Users & groups.

Users and groups from an LDAP directory belong to the directory sync, and an import does not touch them:

The row’s name is held by	Create only	Fail on conflict	Update existing
A directory user or group	Skipped: LDAP users cannot be imported / LDAP groups cannot be imported	Row error: conflict	Row error: LDAP users / groups cannot be imported
Several accounts (a local one and a directory one, say)	Row error	Row error	Row error

A username names exactly one account across the installation (see One username, one account). A name several accounts already share is a row error in every mode — Username “bob” is held by 2 accounts… — because the import cannot tell which one the row means. The same goes for a group’s Members column: a username several accounts share is refused (several accounts have this name; the import cannot tell which one is meant), since a membership granted to it would be granted to nobody anyone can log in as.

A real import does what the form does for each row:

• A new user gets the NT hash PEAP/MSCHAPv2 needs, a password-history entry, the system default language when none is given, and the form’s follow-ups: the welcome email with its set-password link (when SMTP and welcome emails are on), the MFA setup link (when MFA is set to send one automatically) and an auto-issued certificate (when auto-issue is on).
• A changed device or group reaches the daemons as an edit in the console would.
• Every change writes the same audit entry the form writes (USER_CREATED, a device update, each member added or removed…).

A preview does the database work and nothing that cannot be rolled back: it sends no welcome or MFA email, issues no certificate, sends no CoA, tells the daemons nothing, and its audit entries are rolled back with it and never reach your syslog destinations. A preview leaves no trace.

The result separates three kinds of problem:

• The file cannot be read — not UTF-8, not valid JSON, not an .xlsx, no header row, a CSV row with more cells than the header has columns. Nothing is imported, and the drawer says why.
• Notices about the file — an unknown column that was ignored, a repeated column. The import still runs; read them, because an ignored column is usually a typo in a header you meant to change.
• Row errors — one line per refused row, with the spreadsheet row number, the name and the reason in the console’s language, naming the column (Column “CoA Port”: “70000” is outside the allowed range).

An import of a few thousand rows takes a while: each row goes through its service. The console waits up to 10 minutes for an import or export. If the answer does not come in time, the drawer says the outcome is unknown — the server may still be finishing — and refreshes the list. Check what was saved before importing the same file again. The server accepts files up to 3 MB; split a larger file and import the parts one at a time.

Entry	Written when	Details
DATA_EXPORTED	Every export	Entity, format, row count, whether secrets were included
DATA_IMPORTED	Every real import (not a preview)	Entity, format, mode, and the created / updated / skipped / error counts
The form’s own events	Each object created or changed	As if the change had been made in the form

Read them in Logging & Reports → Activity Log (Audit & syslog).

Onboard switches from an inventory sheet. Download the device template. Fill Name, Address and Groups, plus Vendor/Model if your sheet has them. Leave the secret columns out so the devices inherit from their groups. Preview in Create only; rows for devices that already exist show as skipped. Then Import now.

Change one field everywhere. Export the list, delete every column except Name and the one you change, edit, and import in Update existing. Nothing else on the objects moves.

Rotate a group secret without touching the rest. Import a two-column file — Name and RADIUS Secret — for the device groups, in Update existing. Devices with their own secret keep it; the rest inherit the new one.

Re-import an export that carries masks. An export taken without secrets has no secret columns, and one taken with secrets has the values. If you paste •••••••• into a secret column yourself, those rows keep their stored secret.

Lab to production. Export network objects, device groups and devices (in that order) from the lab and import them in the same order, so every name a row refers to already exists. Move users with a temporary password column, or let the welcome email set their passwords.

• Network devices — device fields, secret inheritance and banners
• Users & groups — user and group fields, and one username per account
• Roles & permissions — the create, edit, manage_members actions and who may change whom
• LDAP directories — the accounts and groups an import leaves to the sync
• Audit & syslog — where DATA_EXPORTED and DATA_IMPORTED land
• Backup & upgrades — moving a whole installation, password hashes included