Device Simulation

Synopsis

A simulated device produces its own records instead of collecting them. Nothing needs to exist behind it: no bucket, no cluster, no queue, no host sending syslog. You turn simulation on, choose what the records should look like, and the device starts producing them.

The records it produces are ordinary device data. They pass through the device's pre-processing pipeline, follow its routes, reach its targets, and appear in live capture and in the device's throughput figures exactly as collected records would. That is what makes simulation useful: a pipeline can be built and tested, a target proved end to end, and a Director demonstrated, before the real source is available — or when it can never be reached from where you are working.

Simulation is configured per device. It appears as a Simulation section at the end of the device creation wizard, and on the device's detail page in the same form. Every setting lives under the device's simulation block.

A simulated device proves nothing about the real source

Simulation stands in for the records a device type produces, not for the way it collects them. See Modes below, and read it before you take a green simulated device as evidence that its configuration works.

Modes

How to run chooses between two modes, and they differ in what the device actually is. The field is mode, and it defaults to standalone.

Option	Value	The device's collector
Standalone	standalone	Never starts
Alongside live data	inject	Starts as usual

Standalone

In standalone mode the device's own collector is replaced. It is never started, so no port is bound, no credentials are checked, and no connection to the source is attempted. The device reports itself Connected on the strength of the generator alone, with the detail <type> device is running in simulation mode (<sample>) for <device name>.

The consequence is worth stating plainly, because a green device invites the opposite reading:

• A simulated awss3 device never contacts Amazon S3. It does not authenticate, list a bucket, fetch an object or decode one. A simulated device that reports Connected is not evidence that its bucket name, its region, its credentials or its object format are correct.
• The same holds for every type. A simulated syslog device binds no port, so nothing can send to it; a simulated mssql device runs no query; a simulated kafka device joins no consumer group.

Simulation therefore exercises everything downstream of collection — parsing in your pipeline, field mapping, routing, target delivery — and nothing of the device type's own protocol or decoding. To test the collection itself, turn simulation off and let the real collector run.

Alongside Live Data

In inject mode the device's collector starts exactly as it normally would — it binds, authenticates, and connects — and the generator runs beside it, adding records to whatever arrives. Connection state is still reported by the real collector, so a credential problem still shows up as one.

The two stop together. Stopping or restarting the device stops both the collector and the generator.

Use this mode to raise the volume on a quiet source, to add a record shape the source is not currently producing, or to test a pipeline branch that live traffic rarely reaches.

Supported Device Types

59 device types support simulation. That is every type in the catalog apart from four, and the four are excluded for the same reason: there are no incoming records for the generator to stand in for.

Excluded type	Reason
windows, linux, windows_cluster	Agent devices. Their records come from the collectors running on the enrolled machine rather than from the Director, so there is nothing on the Director's side to stand in for. See Agents
datagen	An outbound generator. It sends traffic to another device over syslog, TCP, UDP or HTTP and never ingests anything, so it has no incoming records to simulate

You do not have to look the list up. The Simulation section is present on every device type that supports it and absent on the four that do not, so the device's own form answers the question. Configuring simulation on an unsupported type is refused with simulation: device type does not support simulation.

Replay device types support simulation as well, on the same terms as the streaming types they mirror — see Replay Devices.

Turning Simulation On

The Simulation mode toggle, status, enables the section. It is off by default, and everything below it appears only once it is on.

Setting	Field	Default	Description
Simulation mode	status	false	Whether this device generates records
How to run	mode	standalone	standalone or inject. See Modes
Sample	sample	custom	The Library sample supplying the template, or custom to write your own
Template	template	-	Your own template, one record per line. Required when sample is custom
Placeholders	placeholders	-	Typed slots the template fills in per record
Events per second	rate	10	Records per second, from 0.01 to 100000
Line order	order	sequential	sequential or random. How a multi-line template is walked
Duration (seconds)	duration	0	Stop generating after this many seconds. 0 means no time limit. At most 2592000 (30 days)
Maximum events	max_events	0	Stop after this many records. 0 means no limit
Source (Optional)	source	-	What the records report as their source. Empty applies the type's default

Devices saved before the rename

This field was labelled Dataset and its key was dataset until this release. A device saved from the web interface keeps working: the platform moves simulation.dataset to simulation.sample in the stored device properties once, and the configuration it generates for the device's Director carries sample from then on. Only a hand-written Director configuration file that still says dataset: has to be changed by hand, since the old key is no longer read.

Choosing What the Records Look Like

A Library Sample

Sample lists the samples the Library offers for this device type — a Cisco ASA firewall stream for a syslog device, AWS CloudTrail records for an S3 device, and so on. In the device creation wizard the field reads Select a sample until one is chosen. A sample carries both a template and its default placeholders, so choosing one is all that is needed to start producing plausible records of that kind.

The dropdown only ever lists samples that apply to this device type, which means a device type no sample has been scoped to is offered very little. Most of the built-in samples are scoped to syslog or S3 devices, so for anything else you will usually clone a built-in and widen it, or write a sample of your own. Samples are described under Library: Samples.

In the web interface a new device arrives at the section with a sample already selected for its type, so turning the toggle on and saving is enough to get records flowing. Change it, or switch to Custom template, at any point. The custom default in the table above is the value that applies when a simulation block leaves sample out altogether, as a hand-written Director configuration may — it is not what the wizard pre-selects for you.

A sample's placeholders are defaults, and you can narrow any of them without editing the sample. Choose Add new placeholder and pick the one to change under Name: the list offers the placeholders the sample defines, and picking one fills in its type and options for you to narrow. It replaces the sample's version for this device only — giving the addresses your own range, or the host names your own list. A hand-written Director configuration can still add a name the sample does not use; the web interface offers only the sample's own.

Your Own Template

Selecting Custom template exposes the Template field. Write one record per line, referencing placeholders as {{name}}:

<134>{{ts}} fw-edge-01 vmfw: action=allow src={{src_ip}}:{{src_port}} dst=203.0.113.9:443 user={{username}}
<134>{{ts}} fw-edge-01 vmfw: action=deny src={{src_ip}}:{{src_port}} dst=203.0.113.9:22 user={{username}}

Declare ts, src_ip and src_port in the Placeholders editor. username needs no entry, because it is a placeholder type in its own right. The full set of types, their options and the timestamp formats are in Simulation Placeholders.

Leaving Template empty on a custom sample is refused with simulation: a custom sample needs a template. In the web interface the same omission is refused with A custom template cannot be empty.

Previewing

Preview records renders a few records from the current template and placeholders using the same generator the Director runs, so you can see the output before saving. The preview names the device type, so a Library sample resolves exactly as it will on the device. It reports Settings changed since this preview once you edit anything.

Pacing and Stopping

Events per second sets the production rate across the device. Fractional rates are accepted, so 0.5 is one record every two seconds. The range is 0.01 to 100000; the upper bound exists so that a mistyped figure cannot flood a Director.

A rate of 0 is refused, not unlimited

0 is below the minimum and is rejected with simulation: rate out of range: 0 (want 0.01..100000). In the web interface the same value is refused with At least 0.01 events per second. To stop a device producing records, turn Simulation mode off or stop the device; there is no rate that means "as fast as possible".

Line order decides how a multi-line template is walked. sequential, the default, cycles the lines in the order they are written, so a template that tells a story — connect, transfer, disconnect — replays it in order. random draws a line at random for each record.

Duration (seconds) and Maximum events both stop generation, whichever is reached first. Either one left at 0 does not apply.

Stopping generation does not stop the device

When a duration or an event limit is reached, the device stops producing records and stays up. In standalone mode it continues to report itself Connected, because nothing has failed — it has simply finished. The console log records Simulation finished for <device name> after <n> records; the device stays up until it is restarted.

Generation does not resume on its own. Restarting the device — by disabling and re-enabling it, or by editing its simulation settings — starts a new run from the beginning, with the counter and the clock reset.

A device with no route attached generates nothing, since there would be nowhere for the records to go. It is not an error and needs no restart: attaching a route starts the flow within a few moments.

The Reported Source

Every record carries a source — the equivalent of the sender address on a listener, or the object path on a store. Source (Optional) overrides it, and may itself use placeholders, so {{src_ip}} makes each record appear to come from a different address.

Left empty, the device type's own default applies:

Device family	Default source
Network listeners, flow collectors, decoys, the Windows Event Collector and eStreamer	127.0.0.1
Object stores and the file collector	simulation/<sample>.log
Queues and streams, databases, Azure Monitor Logs, Microsoft Sentinel, the REST pollers and the stats publisher	simulation.<sample>

<sample> is the name of the sample in use, or custom.

Editing a Running Simulation

Any change under Simulation restarts the device, including turning simulation on or off. The template is prepared once when generation starts, so a changed template, a changed rate, a changed placeholder or a different sample all take effect by way of a restart rather than in place.

A restart is quick, but it does reset the run: the duration clock and the event counter start again from zero, and a sequential template starts again at its first line.

This applies to the sample as well as to the device. If the Library sample a device uses is edited, the device picks up the new version by restarting.

What the Console Log Shows

When generation starts, the device's console log records the settings it started with:

Simulation started for <device name>: sample=<sample> mode=<mode> rate=<n>/s lines=<n> duration=<n>s max_events=<n>

lines is the number of records one full pass of the template produces, which is a quick check that a multi-line template was read as you intended.

If records cannot be written — a target backing up, for instance — the log reports the count every ten seconds rather than once per record: <n> simulated records could not be written for <device name> in the last 10s.

A simulation whose settings do not validate does not start. In standalone mode the device reports a configuration error with the detail Simulation configuration failed for <device name>: <reason>, and stops.

Validation Messages

Settings are validated when you save, so a problem is reported in the form rather than when the device starts.

Message	Cause
simulation: device type does not support simulation	A simulation block on one of the four excluded types
simulation: mode must be standalone or inject	A mode other than those two
simulation: order must be sequential or random	A line order other than those two
simulation: rate out of range	A rate below 0.01 or above 100000, 0 included
simulation: duration out of range	A negative duration, or one over 2592000 seconds
simulation: max_events must not be negative	A negative event limit
simulation: a custom sample needs a template	custom selected with the template left empty
simulation: unknown sample	A sample name the Library does not offer, or one that was deleted after the device was saved
simulation: sample is not available for this device type	A sample scoped to other device types. The full message names the pair: simulation: sample "aws_cloudtrail" is not available for syslog devices

Problems inside the template itself — an undeclared name, an unreadable range — are reported with their own messages, listed under Simulation Placeholders.