# history filter

## Syntax

```
[no] history <instance> filter <string>
```

## Syntax Description

<table><thead><tr><th width="203">Keyword</th><th>Description</th></tr></thead><tbody><tr><td><code>no</code></td><td>(Optional) Removes the history filter.</td></tr><tr><td>instance</td><td>The history instance to be modified. If the specified instance does not exist, it will be created unless the no keyword was also specified. Must be alphanumeric.</td></tr><tr><td>string</td><td>The filter string.</td></tr></tbody></table>

## Defaults

All history events are logged by default.

## Usage Guidelines

Using the history filter command, you can restrict the types of activties that are logged to the history files. The filter syntax is:

&#x20;`<field><op><value>[<cong>…]`

#### Field

The field paramater specifies the field with the history records to test. Valid fields are listed below.&#x20;

Note that the contextual help for this command may list additional field names that are reserved for diagnostic purposes or for future use.

Field names are case-insensitive.

<table><thead><tr><th width="147">Field</th><th>Description</th></tr></thead><tbody><tr><td>time</td><td>The timestamp on the record. The timestamp format for string comparisons is "YYYY-MM-DDTHH:MM:SS.mmm" (e.g., "2024-06-01T19:23:47.316").</td></tr><tr><td>type</td><td>The record type; one of "associate", "disassociate", "access", "session", or "comment".</td></tr><tr><td>count</td><td>For "associate" and "disassociate" records, this is a reference count. For session records with the "fin" flag set, it is the session duration in nanoseconds.</td></tr><tr><td>flags</td><td>A bit field of flags associated with the record. Valid values for Island include "nonrender" (4), "secure" (16), "blocked" (32), "allowed" (64), and "fin" (128).</td></tr><tr><td>mac</td><td>The source MAC address of the packet or device associated with the record.</td></tr><tr><td>ip</td><td>The source IP address of the packet or device associated with the record.</td></tr><tr><td>port</td><td>The source TCP/UDP port number of the packet or device associated with the record.</td></tr><tr><td>destIP</td><td>The destination IP address of the packet associated with the record.</td></tr><tr><td>destPort</td><td>The destination TCP/UDP port number of the packet associated with the record.</td></tr><tr><td>sourceName</td><td>The name of the interface (e.g., "en0") associated with the device on an "associate" or "disassociate" record.</td></tr><tr><td>cat</td><td>The numerical value of the website category associated with the record. The cat field is a bit mask, and is therefore usually best tested using the "&#x26;" operator.</td></tr><tr><td>comment</td><td>A text string containing miscellaneous information associate with some records.</td></tr><tr><td>country</td><td>A two-letter code (e.g., "US") representing the country in which the remote IP address is registered.</td></tr></tbody></table>

#### Op

The comparison operator.&#x20;

<table><thead><tr><th width="128">Operator</th><th>Description</th></tr></thead><tbody><tr><td>=</td><td>Matches if the field value is exactly the same as the comparison value. This can be either a string or a numeric comparson depending on the field and the value.</td></tr><tr><td>!=</td><td>Matches if the field value is not exactly the same as the comparison value. This can be either a string or a numeric comparson depending on the field and the value.</td></tr><tr><td>&#x3C;</td><td>Matches if the field value is numerically less than the comparison value.</td></tr><tr><td>&#x3C;=</td><td>Matches if the field value is numerically less than or equal to the comparison value.</td></tr><tr><td>></td><td>Matches if the field value is numerically greater than the comparison value.</td></tr><tr><td>>=</td><td>Matches if the field value is numerically greater than or equal to the comparison value.</td></tr><tr><td>&#x26;</td><td>Performs a bitwise test.</td></tr></tbody></table>

#### Value

The value to compare against. This can be a string, a regular expression, or a numeric value. Strings must be enclosed in quotes if they contain special characters.

Regular expressions are delineated with a slash (e.g., `mac=/^B4:AE:2B/`). Regular expressions are valid only with the "=" and "!=" operators.

#### Cong

Joins multiple comparison expressions together.

<table><thead><tr><th width="167">Operator</th><th>Description</th></tr></thead><tbody><tr><td>| (vertical bar)</td><td>Logical "or"</td></tr><tr><td>&#x26; (ampersand)</td><td>Logical "and"</td></tr><tr><td>, (comma)</td><td>Logical "and"</td></tr></tbody></table>

## Examples

```
history myhist2 filter "type=associate&mac=00:00:5E:00:53:D2"
history blockedlist filter "flags=/blocked/"
```

## Related Commands


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.islandrouter.com/island-router-cli-2.3.2/commands/history/history-filter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.