urlwatch-filters

title: urlwatch-filters(5)

text:
# urlwatch-filters(5)

## NAME
urlwatch-filters - Filtering output and diff data of urlwatch jobs

## SYNOPSIS
urlwatch --edit

## DESCRIPTION
Each job can have two filter stages configured, with one or more filters processed after each other:

- Applied to the downloaded page before diffing the changes (filter)

- Applied to the diff result before reporting the changes (diff_filter)

While creating your filter pipeline, you might want to preview what the filtered output looks like. You can do so by first configuring your job and then running urlwatch with the --test-filter command, passing in the index (from --list) or the URL/location of the job to be tested:

```
urlwatch --test-filter 1   # Test the first job in the list
urlwatch --test-filter https://example.net/  # Test the job with the given URL
```

The output of this command will be the filtered plaintext of the job, this is the output that will (in a real urlwatch run) be the input to the diff algorithm.

The filter is only applied to new content, the old content was already filtered when it was retrieved. This means that changes to filter are not visible when reporting unchanged contents (see Display for details), and the diff output will be between (old content with filter at the time old content was retrieved) and (new content with current filter).

Once urlwatch has collected at least 2 historic snapshots of a job (two different states of a webpage) you can use the command-line option --test-diff-filter to test your diff_filter settings; this will use historic data cached locally.

## BUILT-IN FILTERS
The list of built-in filters can be retrieved using:

```
urlwatch --features
```

At the moment, the following filters are built-in:

- beautify: Beautify HTML

- css: Filter XML/HTML using CSS selectors

- csv2text: Convert CSV to plaintext

- element-by-class: Get all HTML elements by class

- element-by-id: Get an HTML element by its ID

- element-by-style: Get all HTML elements by style

- element-by-tag: Get an HTML element by its tag

- format-json: Convert to formatted json

- grep: Filter only lines matching a regular expression

- grepi: Remove lines matching a regular expression

- hexdump: Convert binary data to hex dump format

- html2text: Convert HTML to plaintext

- pdf2text: Convert PDF to plaintext

- pretty-xml: Pretty-print XML

- ical2text: Convert iCalendar <https://en.wikipedia.org/wiki/ICalendar> to plaintext

- ocr: Convert text in images to plaintext using Tesseract OCR

- re.sub: Replace text with regular expressions using Python's re.sub

- reverse: Reverse input items

- sha1sum: Calculate the SHA-1 checksum of the content

- shellpipe: Filter using a shell command

- sort: Sort input items

- remove-duplicate-lines: Remove duplicate lines (case sensitive)

- strip: Strip leading and trailing whitespace

- striplines: Strip leading and trailing whitespace in each line

- xpath: Filter XML/HTML using XPath expressions

- jq: Filter, transform and extract values from JSON

## PICKING OUT ELEMENTS FROM A WEBPAGE
You can pick only a given HTML element with the built-in filter, for example to extract
.../
 from a page, you can use the following in your urls.yaml:

```
url: http://example.org/idtest.html
filter:

  - element-by-id: something
```

Also, you can chain filters, so you can run html2text on the result:

```
url: http://example.net/id2text.html
filter:

  - element-by-id: something

  - html2text
```

## CHAINING MULTIPLE FILTERS
The example urls.yaml file also demonstrates the use of built-in filters, here 3 filters are used: html2text, line-grep and whitespace removal to get just a certain info field from a webpage:

```
url: https://example.net/version.html
filter:

  - html2text

  - grep: "Current.*version"

  - strip
```

## EXTRACTING ONLY THE  TAG OF A PAGE
If you want to extract only the body tag you can use this filter:

```
url: https://example.org/bodytag.html
filter:

  - element-by-tag: body
```

## FILTERING BASED ON AN XPATH EXPRESSION
To filter based on an XPath <https://www.w3.org/TR/1999/REC-xpath-19991116/> expression, you can use the xpath filter like so:

```
url: https://example.net/xpath.html
filter:

  - xpath: /html/body/marquee
```

This filters only the <marquee> elements directly below the  element, which in turn must be below the  element of the document, stripping out everything else.

See Microsoft’s XPath Examples <https://msdn.microsoft.com/en-us/library/ms256086(v=vs.110).aspx> page for some other examples. You can also find an XPath of an  node in the Chromium/Google Chrome developer tools by right clicking on the node and selecting copy XPath.

## FILTERING BASED ON CSS SELECTORS
To filter based on a CSS selector <https://www.w3.org/TR/2011/REC-css3-selectors-20110929/>, you can use the css filter like so:

```
url: https://example.net/css.html
filter:

  - css: ul#groceries > li.unchecked
```

This would filter only
 tags directly below
 elements.

Some limitations and extensions exist as explained in cssselect’s documentation <https://cssselect.readthedocs.io/en/latest/#supported-selectors>.

## USING XPATH AND CSS FILTERS WITH XML AND EXCLUSIONS
By default, XPath and CSS filters are set up for HTML documents. However, it is possible to use them for XML documents as well (these examples parse an RSS feed and filter only the titles and publication dates):

```
url: https://example.com/blog/xpath-index.rss
filter:

  - xpath:

      path: '//item/title/text()|//item/pubDate/text()'

      method: xml
```

```
url: http://example.com/blog/css-index.rss
filter:

  - css:

      selector: 'item > title, item > pubDate'

      method: xml

  - html2text: re
```

To match an element in an XML namespace <https://www.w3.org/TR/xml-names/>, use a namespace prefix before the tag name. Use a : to separate the namespace prefix and the tag name in an XPath expression, and use a | in a CSS selector.

```
url: https://example.net/feed/xpath-namespace.xml
filter:

  - xpath:

      path: '//item/media:keywords/text()'

      method: xml

      namespaces:

        media: http://search.yahoo.com/mrss/
```

```
url: http://example.org/feed/css-namespace.xml
filter:

  - css:

      selector: 'item > media|keywords'

      method: xml

      namespaces:

        media: http://search.yahoo.com/mrss/

  - html2text
```

Alternatively, use the XPath expression //*[name()='<tag_name>'] to bypass the namespace entirely.

Another useful option with XPath and CSS filters is exclude. Elements selected by this exclude expression are removed from the final result. For example, the following job will not have any  tag in its results:

```
url: https://example.org/css-exclude.html
filter:

  - css:

      selector: body

      exclude: a
```

## LIMITING THE RETURNED ITEMS FROM A CSS SELECTOR OR XPATH
If you only want to return a subset of the items returned by a CSS selector or XPath filter, you can use two additional subfilters:

- skip: How many elements to skip from the beginning (default: 0)

- maxitems: How many elements to return at most (default: no limit)

For example, if the page has multiple elements, but you only want to select the second and third matching element (skip the first, and return at most two elements), you can use this filter:

```
url: https://example.net/css-skip-maxitems.html
filter:

  - css:

      selector: div.cpu

      skip: 1

      maxitems: 2
```

### Dealing with duplicated results
If you get multiple results on one page, but you only expected one (e.g. because the page contains both a mobile and desktop version in the same HTML document, and shows/hides one via CSS depending on the viewport size), you can use maxitems: 1 to only return the first item.

## FIXING LIST REORDERINGS WITH CSS SELECTOR OR XPATH FILTERS
In some cases, the ordering of items on a webpage might change regularly without the actual content changing. By default, this would show up in the diff output as an element being removed from one part of the page and inserted in another part of the page.

In cases where the order of items doesn't matter, it's possible to sort matched items lexicographically to avoid spurious reports when only the ordering of items changes on the page.

The subfilter for css and xpath filters is sort, and can be true or false (the default):

```
url: https://example.org/items-random-order.html
filter:

  - css:

      selector: span.item

      sort: true
```

## FILTERING PDF DOCUMENTS
To monitor the text of a PDF file, you use the pdf2text filter. It requires the installation of the pdftotext <https://github.com/jalan/pdftotext/blob/master/README.md#pdftotext> library and any of its OS-specific dependencies <https://github.com/jalan/pdftotext/blob/master/README.md#os-dependencies>.

This filter must be the first filter in a chain of filters, since it consumes binary data and outputs text data.

```
url: https://example.net/pdf-test.pdf
filter:

  - pdf2text

  - strip
```

If the PDF file is password protected, you can specify its password:

```
url: https://example.net/pdf-test-password.pdf
filter:

  - pdf2text:

      password: urlwatchsecret

  - strip
```

## DEALING WITH CSV INPUT
The csv2text filter can be used to turn CSV data to a prettier textual representation This is done by supplying a format_string which is a python format string <https://docs.python.org/3/library/string.html#format-string-syntax>.

If the CSV has a header, the format string should use the header names lowercased. For example, let's say we have a CSV file containing data like this:

```
Name;Company
Smith;Initech
Doe;Initech
```

A possible format string for the above CSV (note the lowercase keys):

```
Mr {name} works at {company}
```

If there is no header row, you will need to use the numeric array notation:

```
Mr {0} works at {1}
```

You can force the use of numeric indices with the flag ignore_header.

The key has_header can be used to force use the first line or first ignore the first line as header, otherwise csv.Sniffer <https://docs.python.org/3/library/csv.html#csv.Sniffer> will be used.

## SORTING OF WEBPAGE CONTENT
Sometimes a web page can have the same data between comparisons but it appears in random order. If that happens, you can choose to sort before the comparison.

```
url: https://example.net/sorting.txt
filter:

  - sort
```

The sort filter takes an optional separator parameter that defines the item separator (by default sorting is line-based), for example to sort text paragraphs (text separated by an empty line):

```
url: http://example.org/paragraphs.txt
filter:

  - sort:

      separator: "\n\n"
```

This can be combined with a boolean reverse option, which is useful for sorting and reversing with the same separator (using % as separator, this would turn 3%2%4%1 into 4%3%2%1):

```
url: http://example.org/sort-reverse-percent.txt
filter:

  - sort:

      separator: '%'

      reverse: true
```

## REVERSING OF LINES OR SEPARATED ITEMS
To reverse the order of items without sorting, the reverse filter can be used. By default it reverses lines:

```
url: http://example.com/reverse-lines.txt
filter:

  - reverse
```

This behavior can be changed by using an optional separator string argument (e.g. items separated by a pipe (|) symbol, as in 1|4|2|3, which would be reversed to 3|2|4|1):

```
url: http://example.net/reverse-separator.txt
filter:

  - reverse: '|'
```

Alternatively, the filter can be specified more verbose with a dict. In this example "\n\n" is used to separate paragraphs (items that are separated by an empty line):

```
url: http://example.org/reverse-paragraphs.txt
filter:

  - reverse:

      separator: "\n\n"
```

## WATCHING GITHUB RELEASES AND GITLAB TAGS
This is an example how to watch the GitHub “releases” page for a given project for the latest release version, to be notified of new releases:

```
url: https://github.com/tulir/gomuks/releases
filter:

  - xpath: '(//div[contains(@class,"d-flex flex-column flex-md-row my-5 flex-justify-center")]//h1//a)[1]'

  - html2text: re

  - strip
```

This is the corresponding version for Github tags:

```
url: https://github.com/thp/urlwatch/tags
filter:

  - xpath:

      path: //*[@class="Link--primary"]

      maxitems: 1

  - html2text:
```

and for Gitlab tags:

```
url: https://gitlab.com/chinstrap/gammastep/-/tags
filter:

  - xpath: (//a[contains(@class,"item-title ref-name")])[1]

  - html2text
```

Alternatively, jq can be used for filtering:

```
url: https://api.github.com/repos/voxpupuli/puppet-rundeck/tags
filter:

  - jq: '.[0].name'
```

## REMOVE OR REPLACE TEXT USING REGULAR EXPRESSIONS
Just like Python’s re.sub function, there’s the possibility to apply a regular expression and either remove of replace the matched text. The following example applies the filter 3 times:

1.

Just specifying a string as the value will replace the matches with the empty string.

2.

Simple patterns can be replaced with another string using “pattern” as the expression and “repl” as the replacement.

3.

You can use groups (()) and back-reference them with \1 (etc..) to put groups into the replacement string.

All features are described in Python’s re.sub <https://docs.python.org/3/library/re.html#re.sub> documentation (the pattern and repl values are passed to this function as-is, with the value of repl defaulting to the empty string).

```
url: https://example.com/regex-substitute.html
filter:

    - re.sub: '\s*href="[^"]*"'

    - re.sub:

        pattern: '<h1>'

        repl: 'HEADING 1: '

    - re.sub:

        pattern: '</([^>]*)>'

        repl: '<END OF TAG \1>'
```

If you want to enable certain flags (e.g. re.MULTILINE) in the call, this is possible by inserting an "inline flag" documented in flags in re.compile <https://docs.python.org/3/library/re.html#re.compile>, here are some examples:

- re.MULTILINE: (?m) (Makes ^ match start-of-line and $ match end-of-line)

- re.DOTALL: (?s) (Makes . also match a newline)

- re.IGNORECASE: (?i) (Perform case-insensitive matching)

This allows you, for example, to remove all leading spaces (only space character and tab):

```
url: http://example.com/leading-spaces.txt
filter:

  - re.sub: '(?m)^[ \t]*'
```

## USING A SHELL SCRIPT AS A FILTER
While the built-in filters are powerful for processing markup such as HTML and XML, in some cases you might already know how you would filter your content using a shell command or shell script. The shellpipe filter allows you to start a shell and run custom commands to filter the content.

The text data to be filtered will be written to the standard input (stdin) of the shell process and the filter output will be taken from the shell's standard output (stdout).

For example, if you want to use grep tool with the case insensitive matching option (-i) and printing only the matching part of the line (-o), you can specify this as shellpipe filter:

```
url: https://example.net/shellpipe-grep.txt
filter:

  - shellpipe: "grep -i -o 'price: <span>.*</span>'"
```

This feature also allows you to use sed(1), awk(1) and perl(1) one-liners for text processing (of course, any text tool that works in a shell can be used). For example, this awk(1) one-liner prepends the line number to each line:

```
url: https://example.net/shellpipe-awk-oneliner.txt
filter:

  - shellpipe: awk '{ print FNR " " $0 }'
```

You can also use a multi-line command for a more sophisticated shell script (| in YAML denotes the start of a text block):

```
url: https://example.org/shellpipe-multiline.txt
filter:

  - shellpipe: |

      FILENAME=`mktemp`

      # Copy the input to a temporary file, then pipe through awk

      tee $FILENAME | awk '/The numbers for (.*) are:/,/The next draw is on (.*)./'

      # Analyze the input file in some other way

      echo "Input lines: $(wc -l $FILENAME | awk '{ print $1 }')"

      rm -f $FILENAME
```

Within the shellpipe script, two environment variables will be set for further customization (this can be useful if you have an external shell script file that is used as filter for multiple jobs, but needs to treat each job in a slightly different way):

Environment variable

Contents

$URLWATCH_JOB_NAME

The name of the job (name key in jobs YAML)

$URLWATCH_JOB_LOCATION

The URL of the job, or command line (for shell jobs)

## CONVERTING TEXT IN IMAGES TO PLAINTEXT
The ocr filter uses the Tesseract OCR engine <https://github.com/tesseract-ocr> to convert text in images to plain text. It requires two Python modules to be installed: pytesseract <https://github.com/madmaze/pytesseract> and Pillow <https://python-pillow.org>. Any file formats supported by Pillow (PIL) are supported.

This filter must be the first filter in a chain of filters, since it consumes binary data and outputs text data.

```
url: https://example.net/ocr-test.png
filter:

  - ocr:

      timeout: 5

      language: eng

  - strip
```

The subfilters timeout and language are optional:

- timeout: Timeout for the recognition, in seconds (default: 10 seconds)

- language: Text language (e.g. fra or eng+fra, default: eng)

## FILTERING JSON RESPONSE DATA USING JQ SELECTORS
The jq filter uses the Python bindings for jq <https://stedolan.github.io/jq/>, a lightweight JSON processor. Use of this filter requires the optional jq Python module <https://github.com/mwilliamson/jq.py> to be installed.

```
url: https://example.net/jobs.json
filter:

   - jq:

      query: '.[].title'
```

The subfilter query is optional:

•

query: A valid jq filter string.

Supports aggregations, selections, and the built-in operators like length. For more information on the operations permitted, see the jq Manual <https://stedolan.github.io/jq/manual/>.

## FILES
$XDG_CONFIG_HOME/urlwatch/urls.yaml

## SEE ALSO
urlwatch(1), urlwatch-intro(5), urlwatch-jobs(5)

## COPYRIGHT
2023 Thomas Perl


urlwatch-jobs

title: urlwatch-jobs(5)

text:
# urlwatch-jobs(5)

## NAME
urlwatch-jobs - Job types and configuration for urlwatch

## SYNOPSIS
urlwatch --edit

## DESCRIPTION
Jobs are the kind of things that urlwatch(1) can monitor.

The list of jobs to run are contained in the configuration file urls.yaml, accessed with the command urlwatch --edit, each separated by a line containing only ---. The command urlwatch --list prints the name of each job, along with its index number (1, 2, 3, ...) which gets assigned automatically according to its position in the configuration file.

While optional, it is recommended that each job starts with a name entry:

```
name: "This is a human-readable name/label of the job"
```

The following job types are available:

## URL
This is the main job type -- it retrieves a document from a web server:

```
name: "urlwatch homepage"
url: "https://thp.io/2008/urlwatch/"
```

Required keys:

•

url: The URL to the document to watch for changes

Job-specific optional keys:

- cookies: Cookies to send with the request (see Advanced Topics)

- method: HTTP method to use (default: GET)

- data: HTTP POST/PUT data

- ssl_no_verify: Do not verify SSL certificates (true/false)

- ignore_cached: Do not use cache control (ETag/Last-Modified) values (true/false)

- http_proxy: Proxy server to use for HTTP requests

- https_proxy: Proxy server to use for HTTPS requests

- headers: HTTP header to send along with the request

- encoding: Override the character encoding from the server (see Advanced Topics)

- timeout: Override the default socket timeout (see Advanced Topics)

- ignore_connection_errors: Ignore (temporary) connection errors (see Advanced Topics)

- ignore_http_error_codes: List of HTTP errors to ignore (see Advanced Topics)

- ignore_timeout_errors: Do not report errors when the timeout is hit

- ignore_too_many_redirects: Ignore redirect loops (see Advanced Topics)

(Note: url implies kind: url)

## BROWSER
This job type is a resource-intensive variant of "URL" to handle web pages that require JavaScript to render the content being monitored.

The optional playwright package must be installed in order to run Browser jobs (see Dependencies). You will also need to install the browsers using playwright install (see Playwright Installation <https://playwright.dev/python/docs/intro> for details).

```
name: "A page with JavaScript"
navigate: "https://example.org/"
```

Required keys:

•

navigate: URL to navigate to with the browser

Job-specific optional keys:

- wait_until: Either load, domcontentloaded, networkidle, or commit (see Advanced Topics)

- useragent: User-Agent header used for requests (otherwise browser default is used)

- browser: Either chromium, chrome, chrome-beta, msedge, msedge-beta, msedge-dev, firefox, webkit (must be installed with playwright install)

Because this job uses Playwright <https://playwright.dev/python/> to render the page in a headless browser instance, it uses massively more resources than a "URL" job. Use it only on pages where url does not return the correct results. In many cases, instead of using a "Browser" job, you can use the output of an API called by the page as it loads, which contains the information you are you're looking for by using the much faster "URL" job type.

(Note: navigate implies kind: browser)

## SHELL
This job type allows you to watch the output of arbitrary shell commands, which is useful for e.g. monitoring an FTP uploader folder, output of scripts that query external devices (RPi GPIO), etc...

```
name: "What is in my Home Directory?"
command: "ls -al ~"
```

Required keys:

•

command: The shell command to execute

Job-specific optional keys:

•

stderr: Change how standard error is treated, see below

(Note: command implies kind: shell)

### Configuring stderr behavior for shell jobs
By default urlwatch captures stderr for error reporting (non-zero exit code), but ignores the output when the shell job exits with exit code 0.

This behavior can be customized using the stderr key:

- ignore: Capture stderr, report on non-zero exit code, ignore otherwise (default)

- urlwatch: stderr of the shell job is sent to stderr of the urlwatch process; any error message on stderr will not be visible in the error message from the reporter (legacy default behavior of urlwatch 2.24 and older)

- fail: Treat the job as failed if there is any output on stderr, even with exit status 0

- stdout: Merge stderr output into stdout, which means stderr output is also considered for the change detection/diff part of urlwatch (this is similar to 2>&1 in a shell)

For example, this job definition will make the job appear as failed, even though the script exits with exit code 0:

```
command: |

  echo "Normal standard output."

  echo "Something goes to stderr, which makes this job fail." 1>&2

  exit 0
stderr: fail
```

On the other hand, if you want to diff both stdout and stderr of the job, use this:

```
command: |

  echo "An important line on stdout."

  echo "Another important line on stderr." 1>&2
stderr: stdout
```

## OPTIONAL KEYS FOR ALL JOB TYPES

- name: Human-readable name/label of the job

- filter: Filters (if any) to apply to the output (can be tested with --test-filter)

- max_tries: Number of times to retry fetching the resource

- diff_tool: Command to a custom tool for generating diff text

- diff_filter: Filters (if any) to apply to the diff result (can be tested with --test-diff-filter)

- treat_new_as_changed: Will treat jobs that don't have any historic data as CHANGED instead of NEW (and create a diff for new jobs)

- compared_versions: Number of versions to compare for similarity

- kind (redundant): Either url, shell or browser. Automatically derived from the unique key (url, command or navigate) of the job type

- user_visible_url: Different URL to show in reports (e.g. when watched URL is a REST API URL, and you want to show a webpage)

## SETTING KEYS FOR ALL JOBS AT ONCE
The main Configuration file has a job_defaults key that can be used to configure keys for all jobs at once.

See urlwatch-config(5) for how to configure job defaults.

## EXAMPLES
See urlwatch-cookbook(7) for example job configurations.

## FILES
$XDG_CONFIG_HOME/urlwatch/urls.yaml

## SEE ALSO
urlwatch(1), urlwatch-intro(5), urlwatch-filters(5)

## COPYRIGHT
2023 Thomas Perl


urlwatch-reporters

title: urlwatch-reporters(5)

summary: Reporters for change notifications

text:
# urlwatch-reporters(5)

## NAME
urlwatch-reporters - Reporters for change notifications

## SYNOPSIS
urlwatch --edit-config

## DESCRIPTION
By default urlwatch(1) prints out information about changes to standard output, which is your terminal if you run it interactively. If running via cron(8) or another scheduler service, it depends on how the scheduler is configured.

You can enable one or more additional reporters that are used to send change notifications. Please note that most reporters need additional dependencies installed.

See urlwatch-config(5) for generic config settings.

To send a test notification, use the --test-reporter command-line option with the name of the reporter:

```
urlwatch --test-reporter stdout
```

This will create a test report with new, changed, unchanged and error notifications (only the ones configured in display in the Configuration will be shown in the report) and send it via the stdout reporter (if it is enabled).

To test if your e-mail reporter is configured correctly, you can use:

```
urlwatch --test-reporter email
```

Any reporter that is configured and enabled can be tested.

If the notification does not work, check your configuration and/or add the --verbose command-line option to show detailed debug logs.

## BUILT-IN REPORTERS
The list of built-in reporters can be retrieved using:

```
urlwatch --features
```

At the moment, the following reporters are built-in:

- discord: Send a message to a Discord channel

- email: Send summary via e-mail / SMTP

- ifttt: Send summary via IFTTT

- mailgun: Send e-mail via the Mailgun service

- matrix: Send a message to a room using the Matrix protocol

- mattermost: Send a message to a Mattermost channel

- prowl: Send a detailed notification via prowlapp.com

- pushbullet: Send summary via pushbullet.com

- pushover: Send summary via pushover.net

- shell: Pipe a message to a shell command

- slack: Send a message to a Slack channel

- stdout: Print summary on stdout (the console)

- telegram: Send a message using Telegram

- xmpp: Send a message using the XMPP Protocol

## PUSHOVER
You can configure urlwatch to send real time notifications about changes via Pushover <https://pushover.net/>. To enable this, ensure you have the chump python package installed (see Dependencies). Then edit your config (urlwatch --edit-config) and enable pushover. You will also need to add to the config your Pushover user key and a unique app key (generated by registering urlwatch as an application on your Pushover account <https://pushover.net/apps/build>.

You can send to a specific device by using the device name, as indicated when you add or view your list of devices in the Pushover console. For example device: 'MyPhone', or device: 'MyLaptop'. To send to all of your devices, set device: null in your config (urlwatch --edit-config) or leave out the device configuration completely.

Setting the priority is possible via the priority config option, which can be lowest, low, normal, high or emergency. Any other setting (including leaving the option unset) maps to normal.

## PUSHBULLET
Pushbullet notifications are configured similarly to Pushover (see above). You’ll need to add to the config your Pushbullet Access Token, which you can generate at https://www.pushbullet.com/#settings

## TELEGRAM
Telegram notifications are configured using the Telegram Bot API. For this, you’ll need a Bot API token and a chat id (see https://core.telegram.org/bots). Sample configuration:

```
telegram:

  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token

  chat_id: '88888888' # the chat id where the messages should be sent

  enabled: true
```

Messages can be sent silently (silent) if you prefer notifications with no sounds, and monospace formatted (monospace). By default notifications are not silent and no formatting is done.

```
telegram:

  # ...

  silent: true # message is sent silently

  monospace: true # display message as pre-formatted code block
```

To set up Telegram, from your Telegram app, chat up BotFather (New Message, Search, “BotFather”), then say /newbot and follow the instructions. Eventually it will tell you the bot token (in the form seen above, <number>:<random string>) - add this to your config file.

You can then click on the link of your bot, which will send the message /start. At this point, you can use the command urlwatch --telegram-chats to list the private chats the bot is involved with. This is the chat ID that you need to put into the config file as chat_id. You may add multiple chat IDs as a YAML list:

```
telegram:

  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token

  chat_id:

    - '11111111'

    - '22222222'

  enabled: true
```

Don’t forget to also enable the reporter.

## SLACK
Slack notifications are configured using “Slack Incoming Webhooks”. Here is a sample configuration:

```
slack:

  webhook_url: 'https://hooks.slack.com/services/T50TXXXXXU/BDVYYYYYYY/PWTqwyFM7CcCfGnNzdyDYZ'

  enabled: true
```

To set up Slack, from you Slack Team, create a new app and activate “Incoming Webhooks” on a channel, you’ll get a webhook URL, copy it into the configuration as seen above.

## MATTERMOST
Mattermost notifications are set up the same way as Slack notifications, the webhook URL is different:

```
mattermost:

  webhook_url: 'http://{your-mattermost-site}/hooks/XXXXXXXXXXXXXXXXXXXXXX'

  enabled: true
```

See Incoming Webooks <https://developers.mattermost.com/integrate/incoming-webhooks/> in the Mattermost documentation for details.

## DISCORD
Discord notifications are configured using “Discord Incoming Webhooks”. Here is a sample configuration:

```
discord:

   webhook_url: 'https://discordapp.com/api/webhooks/11111XXXXXXXXXXX/BBBBYYYYYYYYYYYYYYYYYYYYYYYyyyYYYYYYYYYYYYYY'

   enabled: true

   embed: true

   colored: true

   subject: '{count} changes: {jobs}'
```

To set up Discord, from your Discord Server settings, select Integration and then create a "New Webhook", give the webhook a name to post under, select a channel, push "Copy Webhook URL" and paste it into the configuration as seen above.

Embedded content might be easier to read and identify individual reports. Subject precedes the embedded report and is only used when embed is true.

When colored is true reports will be embedded in code section (with diff syntax) to enable colors.

## IFTTT
To configure IFTTT events, you need to retrieve your key from here:

https://ifttt.com/maker_webhooks/settings

The URL shown in "Account Info" has the following format:

```
https://maker.ifttt.com/use/{key}
```

In this URL, {key} is your API key. The configuration should look like this (you can pick any event name you want):

```
ifttt:

  enabled: true

  key: aA12abC3D456efgHIjkl7m

  event: event_name_you_want
```

The event will contain three values in the posted JSON:

- value1: The type of change (new, changed, unchanged or error)

- value2: The name of the job (name key in jobs.yaml)

- value3: The location of the job (url, command or navigate key in jobs.yaml)

These values will be passed on to the Action in your Recipe.

## MATRIX
You can have notifications sent to you through the Matrix protocol <https://matrix.org>.

To achieve this, you first need to register a Matrix account for the bot on any homeserver.

You then need to acquire an access token and room ID, using the following instructions adapted from this guide <https://t2bot.io/docs/access_tokens/>:

1.

Open Riot.im <https://riot.im/app/> in a private browsing window

2.

Register/Log in as your bot, using its user ID and password.

3.

Set the display name and avatar, if desired.

4.

In the settings page, select the "Help & About" tab, scroll down to the bottom and click Access Token: <click to reveal>.

5.

Copy the highlighted text to your configuration.

6.

Join the room that you wish to send notifications to.

7.

Go to the Room Settings (gear icon) and copy the Internal Room ID from the bottom.

8.

Close the private browsing window but do not log out, as this invalidates the Access Token.

Here is a sample configuration:

```
matrix:

  homeserver: https://matrix.org

  access_token: "YOUR_TOKEN_HERE"

  room_id: "!roomroomroom:matrix.org"

  enabled: true
```

You will probably want to use the following configuration for the markdown reporter, if you intend to post change notifications to a public Matrix room, as the messages quickly become noisy:

```
markdown:

  details: false

  footer: false

  minimal: true

  enabled: true
```

## E-MAIL VIA GMAIL SMTP
You need to configure your GMail account to allow for “less secure” (password-based) apps to login:

1.

Go to https://myaccount.google.com/

2.

Click on “Sign-in & security”

3.

Scroll all the way down to “Allow less secure apps” and enable it

You do not want to do this with your primary GMail account, but rather on a separate account that you create just for sending mails via urlwatch. Allowing less secure apps and storing the password (even if it's in the keychain) is not good security practice for your primary account.

Now, start the configuration editor:

```
urlwatch --edit-config
```

These are the keys you need to configure:

```
report:

  email:

    enabled: true

    from: your.username@gmail.com

    to: your.destination.email@example.com

    method: smtp

    smtp:

      host: smtp.gmail.com

      auth: true

      port: 587

      starttls: true
```

The password is best stored in your keychain, and not in the config file. To store the password, run:

```
urlwatch --smtp-login
```

This will query your password, check the login, and store it in your keychain. Subsequent runs will use this password for logging in.

## E-MAIL VIA AMAZON SIMPLE E-MAIL SERVICE (SES)
Same as the GMail configuration above, but use e.g. email-smtp.us-west-2.amazonaws.com as the SMTP host, and username and port settings according to SES's login page.

## SMTP LOGIN WITHOUT KEYRING
If for whatever reason you cannot use a keyring to store your password (for example, when using it from a cron job) you can also set the insecure_password option in the SMTP config:

```
report:

  email:

    smtp:

      auth: true

      insecure_password: secret123
```

The insecure_password key will be preferred over the data stored in the keyring. Please note that as the name says, storing the password as plaintext in the configuration is insecure and bad practice, but for an e-mail account that’s only dedicated for sending mails this might be a way. Never ever use this with your your primary e-mail account! Seriously! Create a throw-away GMail (or other) account just for sending out those e-mails or use local sendmail with a mail server configured instead of relying on SMTP and password auth.

Note that this makes it really easy for your password to be picked up by software running on your machine, by other users logged into the system and/or for the password to appear in log files accidentally.

## XMPP
You can have notifications sent to you through the XMPP protocol.

To achieve this, you should register a new XMPP account that is just used for urlwatch.

Here is a sample configuration:

```
xmpp:

  enabled: true

  sender: "BOT_ACCOUNT_NAME"

  recipient: "YOUR_ACCOUNT_NAME"
```

The password is not stored in the config file, but in your keychain. To store the password, run: urlwatch --xmpp-login and enter your password.

If for whatever reason you cannot use a keyring to store your password you can also set the insecure_password option in the XMPP config. For more information about the security implications, see SMTP login without keyring.

## PROWL
You can have notifications sent to you through the Prowl push notification service, to receive the notification on iOS.

To achieve this, you should register a new Prowl account, and have the Prowl application installed on your iOS device.

To create an API key for urlwatch:

1.

Log into the Prowl website at https://prowlapp.com/

2.

Navigate to the “API Keys” tab.

3.

Scroll to the “Generate a new API key” section.

4.

Give the key a note that will remind you you've used it for urlwatch.

5.

Press “Generate Key”

6.

Copy the resulting key.

Here is a sample configuration:

```
prowl:

  enabled: true

  api_key: '<your api key here>'

  priority: 2

  application: 'urlwatch example'

  subject: '{count} changes: {jobs}'
```

The “subject" field is similar to the subject field in the email, and will be used as the name of the Prowl event. The application is prepended to the event and shown as the source of the event in the Prowl App.

## SHELL
This is a simple reporter that pipes the text report notification to a command of your choice. The command is run using Python's subprocess.Popen() <https://docs.python.org/3/library/subprocess.html#popen-constructor> with shell=False (to avoid possibly-unwanted shell expansion). Of course, you can create your own shell script that does shell expansion and other things, and call that from the command.

The key ignore_stdout (defaults to true) can be used to ignore any output the program writes on stdout. The key ignore_stderr (defaults to false) can be used to ignore any output the program writes on stderr.

If stdout/stderr are not ignored, urlwatch will log any possible output in its --verbose log.

The report written to stdin of the process is based on the output of the text reporter, configuring the text reporter will adjust the data sent to the shell reporter.

For example, to simply append reports to a file, configure it like this:

```
shell:

  enabled: true

  command: ['tee', '-a', '/path/to/log.txt']

  ignore_stdout: true
```

## FILES
$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

## SEE ALSO
urlwatch(1), urlwatch-config(5), urlwatch-intro(7), urlwatch-cookbook(7)

## COPYRIGHT
2023 Thomas Perl


quotagrpadmins

package: quota

title: quotagrpadmins(5)

summary: users responsible for group disk usage

text:
# quotagrpadmins(5)

## NAME
quotagrpadmins - users responsible for group disk usage

## SYNOPSIS
/etc/quotagrpadmins

## DESCRIPTION
The quotagrpadmins file lists administrators of user groups who will receive a warning if warnquota --group command finds a group exceeding its disk usage limits.

Each line consists of a group name followed by a colon and a user name. White space characters surrounding the names are allowed. Empty lines or lines starting with a hash sign or a semicolon are ignored.

## EXAMPLE
\# comment

users: root

## FILES
/etc/quotagrpadmins

list of group administrators

## SEE ALSO
warnquota(8).


quotatab

title: quotatab(5)

text:
# quotatab(5)

## NAME
quotatab - Descriptions of devices with disk quotas

## SYNOPSIS
/etc/quotatab

## DESCRIPTION
The quotatab file lists human descriptions of devices for the purpose of warnquota(8) notifications.

Each line consists of a device path name followed by a colon and a description. White space, apostrophe, and double quote characters surrounding the names and descriptions will be stripped. The description field can encode a new-line as a pipe character.

Empty lines or lines starting with a hash sign or a semicolon are ignored.

## EXAMPLE
\# comment

/dev/sda2: Home directories.|This becomes the second line.

## FILES
/etc/quotatab

list of device descriptions

## SEE ALSO
warnquota(8).


warnquota.conf

title: warnquota.conf(5)

summary: configuration for warnquota

text:
# warnquota.conf(5)

## NAME
warnquota.conf - configuration for warnquota

## SYNOPSIS
/etc/warnquota.conf

## DESCRIPTION
The warnquota.conf file stores a configuration for warnquota(8) tool which is used to notify a user or a group who exceeds its disk quota limits.

The syntax is an option name followed by an equal sign and the option value. White space characters surrounding the option names and values are allowed.

Empty lines or lines starting with a hash sign or a semicolon are ignored.

An option value can but does not have to be quoted. The value can span across multiple lines provided each previous line ends with a backslash.

Some option values can contain formatting sequences which will be expanded to their respective values. Following sequences are recognized:

%d

domain name

%h

host name

%i, %s

user or group name

%%

literal % character

|

new-line character

## OPTIONS
CC_BEFORE

Send to copy-carbon address only when a user has less than specified grace time left. Value is a number followed by a time unit. Known units are seconds, minutes, hours, and days. Example: 5 days

CC_TO

An e-mail address to put into copy-carbon (CC:) recipient header. Default value is root.

CHARSET

Defines character set for sent e-mails. Default value will be current locale character set used when executing warnquota command, if locale is not either C or POSIX. Otherwise no character set will be specified in the e-mails.

FROM

Defines From: e-email address. Default value is support@localhost.

GROUP_MESSAGE

A text sent as an e-mail body if a group exceeds its limits. This option recognizes formatting sequences.

GROUP_SIGNATURE

A signature text appended to notification for a group. Default value is a general explanation utilizing SUPPORT and PHONE values. This option recognizes formatting sequences.

LDAP_BASEDN

Base distinguished name for LDAP queries.

LDAP_BINDDN

Bind distinguished name for LDAP queries.

LDAP_BINDPW

Bind password for LDAP queries.

LDAP_DEFAULT_MAIL_DOMAIN

Default e-mail address domain of searched user if given LDAP attribute does not specify any.

LDAP_HOST

LDAP server name to connect to if LDAP_URI is not defined.

LDAP_MAIL

A boolean controlling if LDAP has to be used to look up user's e-mail address. Possible values are true and false. Default value is false.

LDAP_MAIL_ATTRIBUTE

The LDAP attribute which holds user's e-mail address.

LDAP_PORT

LDAP server port number to connect to if LDAP_URI is not defined.

LDAP_SEARCH_ATTRIBUTE

The LDAP attribute which holds user's ID to look up.

LDAP_URI

The URL of LDAP server to use to search user's e-mail addresses. This option takes preference over LDAP_HOST and LDAP_PORT. Example: ldaps://example.com:389/

MESSAGE

A beginning of text sent as an e-mail body if a user exceeds his limits. This option recognizes formatting sequences.

MAIL_CMD

The command to execute to send an e-mail. The e-mail text including all headers is passed to the standard input of the command. Default value is /usr/lib/sendmail -t.

MAILDEV

The device with disk quotas to exclude from sending notifications if there are exceeded limits. This option should identify the device where mail boxes are stored to prevent from bouncing the warnquota notification by local MDA due to no space for storing new e-mails. Special value any denotes all devices.

PHONE

The telephone contact to the user support. Default value is (xxx) xxx-xxxx or (yyy) yyy-yyyy.

SIGNATURE

The end of e-mail body if a user exceeds its limits. Default value is a general explanation utilizing SUPPORT and PHONE values. This option recognizes formatting sequences.

SUBJECT

The text to put into Subject: header. Default value is Disk Quota usage on system.

SUPPORT

The contact to the user support. Default value is support@localhost.

## EXAMPLE
\# comment

FROM = root@example.com SUPPORT = support@example.com PHONE = 1234

## FILES
/etc/warnquota.conf

configuration for warnquota(8)

## SEE ALSO
warnquota(8).


quvirc

package: quvi

title: quvirc(5)

text:
# quvirc(5)

## NAME
quvirc - The simple configuration file for the quvi program

## DESCRIPTION
A quvi configuration file consists of groups of key-value pairs similar to the so called .ini-like configuration files. quvi uses the GLib to parse the configuration. GLib refers to these files as key files, for lack of a better name.

The lines beginning with a # are considered as comments. You can annotate your configuration file using this character. All text after the comment character to the end of the line is ignored.

GKeyFile has some limitations that should be considered when you use a configuration file to configure quvi.

Multiple keys

Each group in each configuration file may contain the same key multiple times, note however that the last key value replaces the previously defined value.

Multiple groups

Configuration files may contain multiple groups with the same file, they are however, merged together.

The syntax of the configuration file is described in detail in the Desktop Entry Specification at http://freedesktop.org/Standards/desktop-entry-spec

GKeyFile is described in detail in the GLib reference documentation at http://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html

## PATHS
The program will by default search the quvirc file from the typical configuration file paths. These paths (order and location) are determined by GLib, based on how it was configured.

•Print the search paths:

```
$ quvi info --print-config-paths
/usr/share/gnome/quvi/quvirc
/usr/share/gdm/quvi/quvirc
/usr/local/share/quvi/quvirc
/usr/share/quvi/quvirc
/home/legatvs/.local/share/quvi/quvirc
/home/legatvs/.config/quvi/quvirc
```

Each of the same group variable value read from another quvirc replaces the current value. For example:

```
~/.local/share/quvi/quvirc
[core]
stream = foo
~/.config/quvi/quvirc
[core]
stream = bar
```

The program would use "bar" as the core.stream value.

## EXAMPLES
A given quvirc could look like:

```
[core]
check-mode-offline = true
print-format = json
subtitle-language = cc_en,tts_en
stream = 480p,720p,best
#verbosity = debug
[dump]
query-metainfo = true
[exec]
enable-stdout = true
external = echo %t,mplayer %u
[get]
output-regex = %t:/\\w|\\s/,%t:s/\\s\\s+/ /
output-name = %t_%i.%e
resume-from = -1
throttle = 500
[http]
#user-agent = foo/1.0
enable-cookies = true
```

## SEE ALSO
quvi-info(1), quvi-dump(1), quvi-get(1), quvi-scan(1)

## FURTHER RESOURCES
Home

http://quvi.sourceforge.net/

Development code

git://repo.or.cz/quvi-tool.git

gitweb

http://repo.or.cz/w/quvi-tool.git

## AUTHORS
Toni Gundogdu <legatvs@gmail.com>

Author.

## REPORTING BUGS
Report bugs to the quvi-devel mailing list <quvi-devel@lists.sourceforge.net> where the development and the maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## LICENSE
quvi is Free Software licensed under the GNU Affero GPLv3+

## QUVI
Part of the quvi(1) suite


rabbitmq-env.conf

package: rabbitmq-server

title: rabbitmq-env.conf(5)

text:
# rabbitmq-env.conf(5)

## NAME
rabbitmq-env.conf — environment variables used by RabbitMQ server

## DESCRIPTION
rabbitmq-env.conf contains environment variables that override the defaults built in to the RabbitMQ scripts and CLI tools.

The file is interpreted by the system shell, and so should consist of a sequence of shell environment variable definitions. Normal shell syntax is permitted (since the file is sourced using the shell "." operator), including line comments starting with "#".

In order of preference, the startup scripts get their values from the environment, from rabbitmq-env.conf and finally from the built-in default values. For example, for the RABBITMQ_NODENAME setting, RABBITMQ_NODENAME from the environment is checked first. If it is absent or equal to the empty string, then NODENAME from rabbitmq-env.conf is checked. If it is also absent or set equal to the empty string then the default value from the startup script is used.

The variable names in rabbitmq-env.conf are always equal to the environment variable names, with the "RABBITMQ_" prefix removed: RABBITMQ_NODE_PORT from the environment becomes NODE_PORT in rabbitmq-env.conf.

## EXAMPLES
Below is an example of a minimalistic rabbitmq-env.conf file that overrides the default node name prefix from "rabbit" to "hare".

\# I am a complete rabbitmq-env.conf file.

\# Comment lines start with a hash character.

\# This is a /bin/sh script file - use ordinary envt var syntax

NODENAME=hare

In the below rabbitmq-env.conf file RabbitMQ configuration file location is changed to "/data/services/rabbitmq/rabbitmq.conf".

\# I am a complete rabbitmq-env.conf file.

\# Comment lines start with a hash character.

\# This is a /bin/sh script file - use ordinary envt var syntax

CONFIG_FILE=/data/services/rabbitmq/rabbitmq.conf

## SEE ALSO
rabbitmq-plugins(8), rabbitmq-server(8), rabbitmq-queues(8), rabbitmq-streams(8), rabbitmq-upgrade(8), rabbitmqctl(8)

## AUTHOR
The RabbitMQ Team <contact-tanzu-data.pdl@broadcom.com>


radvd.conf

package: radvd

title: radvd.conf(5)

text:
# radvd.conf(5)

## NAME
radvd.conf - configuration file of the router advertisement daemon radvd

## DESCRIPTION
This file describes the information which is included in the router advertisement (RA) of a specific interface.

The file contains one or more interface definitions of the form:

```
interface name {
	list of interface specific options
	list of prefix definitions
	list of clients (IPv6 addresses) to advertise to
	list of route definitions
	list of RDNSS definitions
	list of DNSSL definitions
	list of ABRO definitions
	list of NAT64 pref64 definitions
	list of auto-ignore prefixes
	list of acceptable RA source addresses
};
```

All the possible interface specific options are detailed below. Each option has to be terminated by a semicolon. Options are not case sensitive.

Prefix definitions are of the form:

```
prefix prefix/length {
	list of prefix specific options
};
```

Prefix can be network prefix or the address of the interface. The address of interface should be used when using Mobile IPv6 extensions.

Special prefix "::/64" is also supported on systems that implement getifaddrs() (on other systems, configuration activation fails and radvd exits). When configured, radvd picks all non-link-local prefix assigned to the interface and starts advertising it (unless ignored with autoignoreprefixes). This may be applicable in non-6to4 scenarios where the upstream prefix might change. This option is incompatible with Base6to4Interface option. AdvRouterAddr option is always enabled when this configuration is used.

All the possible prefix specific options are described below. Each option has to be terminated by a semicolon.

Decimal values are allowed only for MinDelayBetweenRAs, MaxRtrAdvInterval and MinRtrAdvInterval. Decimal values should be used only when using Mobile IPv6 extensions.

Route definitions are of the form:

```
route prefix/length {
	list of route specific options
};
```

The prefix of a route definition should be network prefix; it can be used to advertise more specific routes to the hosts.

RDNSS (Recursive DNS server) definitions are of the form:

```
RDNSS ip [ip] [ip] {
	list of rdnss specific options
};
```

Each RDNSS definition block has a maximum length of 2040 bytes including the header, this accomodates up to 127 addresses.

If the length is exceeded, radvd will log a non-fatal error instead of sending the option.

DNSSL (DNS Search List) definitions are of the form:

```
DNSSL suffix [suffix] [suffix] [...] {
	list of dnssl specific options
};
```

Each DNSSL definition block has a maximum length of 2040 bytes including the header, applied after the suffixes are encoded per RFC1035, section 3.1.

If the length is exceeded, radvd will log a non-fatal error instead of sending the option.

By default radvd will send multicast route advertisements so that every node on the link can use them. The list of clients (IPv6 address) to advertise to, and accept route solicitations from can be configured. If done, radvd does not send messages to the multicast addresses but to the configured unicast addresses only. Solicitations from other addresses are refused unless UnrestrictedUnicast is enabled. This is similar to UnicastOnly but includes periodic messages and incoming client access configuration. See examples section for a use case of this.

The definitions are of the form:

```
clients {

        list of IPv6 addresses
};
```

Clients can be prefixed with "!" to ignore them completely and never send advertisements to them.

By default radvd will use the first link-local address for the interface as the source address for route advertisements. This can be overwritten by manually setting the list of acceptable source addresses. If done, radvd will use the first address from the interface that is present in the configured source addresses only. This functionality will NOT spoof the source address, but may be useful in combination with VRRP or other functionality that do a virtual/failover MAC.

```
AdvRASrcAddress {

        list of IPv6 addresses
};
```

ABRO (Authoritative Border Router Option) definitions are of the form:

```
abro IPv6-address {

        list of abro specific options
};
```

NAT64 pref64 (the NAT64 prefix included in the router advertisements):

```
nat64prefix prefix/length {
	list of NAT64 prefix specific options
};
```

The value of length can only be one of /32, /40, /48, /56, /64, or /96.

When using the special prefix "::/64" this option forms an ignore list for prefixes that should not be automatically generated and advertised. Has no effect on any other prefix definition.

The definitions are of the form:

```
autoignoreprefixes {

        list of IPv6 prefixes
};
```

## INTERFACE SPECIFIC OPTIONS
IgnoreIfMissing on|off

A flag indicating whether or not the interface is ignored if it does not exist at start-up.

This is useful for dynamic interfaces which are not active when radvd starts or which are dynamically disabled and re-enabled during the time radvd runs.

Current versions of radvd automatically try to re-enable interfaces.

Enabling IgnoreIfMissing also quenches certain warnings in log messages relating to missing interfaces.

Default: on

AdvSendAdvert on|off

A flag indicating whether or not the router sends periodic router advertisements and responds to router solicitations.

This option no longer has to be specified first, but it needs to be on to enable advertisement on this interface.

Default: off

UnicastOnly on|off

Indicates that the interface link type only supports unicast. This will prevent unsolicited advertisements from being sent, and will cause solicited advertisements to be unicast to the soliciting node. This option is necessary for non-broadcast, multiple-access links, such as ISATAP.

Default: off

UnrestrictedUnicast on|off

A flag indicating whether or not to respond to router solicitations when there is a list of clients configured.

This allows regular unsolicited advertisements to be sent to some clients without ignoring router solicitations from unknown clients.

Default: off

AdvRASolicitedUnicast on|off

Indicates that router solicitations will be responded to with unicast router advertisements, as recommended by RFC7772. Large networks with a high concentration of mobile devices might experience like battery depletion, when solicited Router Advertisement messages are multicast.

This corresponds to the Cisco IOS option ipv6 nd ra solicited unicast

Default: on

MaxRtrAdvInterval seconds

The maximum time allowed between sending unsolicited multicast router advertisements from the interface, in seconds.

Must be no less than 4 seconds and no greater than 65535 seconds.

Minimum when using Mobile IPv6 extensions: 0.07.

For values less than 0.2 seconds, 0.02 seconds is added to account for scheduling granularities as specified in RFC3775.

Default: 600 seconds

MinRtrAdvInterval seconds

The minimum time allowed between sending unsolicited multicast router advertisements from the interface, in seconds.

Must be no less than 3 seconds and no greater than 0.75 * MaxRtrAdvInterval.

Minimum when using Mobile IPv6 extensions: 0.03.

Default: 0.33 * MaxRtrAdvInterval

MinDelayBetweenRAs seconds

The minimum time allowed between sending multicast router advertisements from the interface, in seconds.

This applies to solicited multicast RAs. This is defined as the protocol constant MIN_DELAY_BETWEEN_RAS in RFC4861. MIPv6 redefines this parameter to have a minimum of 0.03 seconds.

Minimum when using Mobile IPv6 extensions: 0.03.

Default: 3

AdvManagedFlag on|off

When set, hosts use the administered (stateful) protocol for address autoconfiguration in addition to any addresses autoconfigured using stateless address autoconfiguration. The use of this flag is described in RFC 4862.

Default: off

AdvOtherConfigFlag on|off

When set, hosts use the administered (stateful) protocol for autoconfiguration of other (non-address) information. The use of this flag is described in RFC 4862.

Default: off

AdvLinkMTU integer

The MTU option is used in router advertisement messages to ensure that all nodes on a link use the same MTU value in those cases where the link MTU is not well known.

If specified, i.e. not 0, must not be smaller than 1280 and not greater than the maximum MTU allowed for this link (e.g. ethernet has a maximum MTU of 1500. See RFC 4864).

Default: 0

AdvReachableTime milliseconds

The time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation. Used by the Neighbor Unreachability Detection algorithm (see Section 7.3 of RFC 4861). A value of zero means unspecified (by this router).

Must be no greater than 3,600,000 milliseconds (1 hour).

Default: 0

AdvRetransTimer milliseconds

The time, in milliseconds, between retransmitted Neighbor Solicitation messages. Used by address resolution and the Neighbor Unreachability Detection algorithm (see Sections 7.2 and 7.3 of RFC 4861). A value of zero means unspecified (by this router).

Default: 0

AdvCurHopLimit integer

The default value that should be placed in the Hop Count field of the IP header for outgoing (unicast) IP packets. The value should be set to the current diameter of the Internet. The value zero means unspecified (by this router).

Default: 64

AdvDefaultLifetime seconds

The lifetime associated with the default router in units of seconds. The maximum value corresponds to 18.2 hours. A lifetime of 0 indicates that the router is not a default router and should not appear on the default router list. The router lifetime applies only to the router's usefulness as a default router; it does not apply to information contained in other message fields or options. Options that need time limits for their information include their own lifetime fields.

Must be either zero or between MaxRtrAdvInterval and 65535 seconds.

Default: 3 * MaxRtrAdvInterval (Minimum 1 second).

AdvDefaultPreference low|medium|high

The preference associated with the default router, as either "low", "medium", or "high".

Default: medium

AdvSourceLLAddress on|off

When set, the link-layer address of the outgoing interface is included in the RA.

Default: on

RemoveAdvOnExit on|off

Upon shutdown, send a final advertisement with zero Router Lifetime. This should cause the router and routes to be immediately removed from the receiving end-nodes' route table. This may need to be disabled ("off") in an vrrp or carp setup.

Default: on

AdvHomeAgentFlag on|off

When set, indicates that sending router is able to serve as Mobile IPv6 Home Agent. When set, minimum limits specified by Mobile IPv6 are used for MinRtrAdvInterval and MaxRtrAdvInterval.

Default: off

AdvHomeAgentInfo on|off

When set, Home Agent Information Option (specified by Mobile IPv6) is included in Router Advertisements. AdvHomeAgentFlag must also be set when using this option.

Default: off

HomeAgentLifetime seconds

The length of time in seconds (relative to the time the packet is sent) that the router is offering Mobile IPv6 Home Agent services. A value 0 must not be used. The maximum lifetime is 65520 seconds (18.2 hours). This option is ignored, if AdvHomeAgentInfo is not set.

If both HomeAgentLifetime and HomeAgentPreference are set to their default values, Home Agent Information Option will not be sent.

Default: AdvDefaultLifetime

HomeAgentPreference integer

The preference for the Home Agent sending this Router Advertisement. Values greater than 0 indicate more preferable Home Agent, values less than 0 indicate less preferable Home Agent. This option is ignored, if AdvHomeAgentInfo is not set.

If both HomeAgentLifetime and HomeAgentPreference are set to their default values, Home Agent Information Option will not be sent.

Default: 0

AdvMobRtrSupportFlag on|off

When set, the Home Agent signals it supports Mobile Router registrations (specified by NEMO Basic). AdvHomeAgentInfo must also be set when using this option.

Default: off

AdvIntervalOpt on|off

When set, Advertisement Interval Option (specified by Mobile IPv6) is included in Router Advertisements. When set, minimum limits specified by Mobile IPv6 are used for MinRtrAdvInterval and MaxRtrAdvInterval.

The advertisement interval is based on the configured MaxRtrAdvInterval parameter except where this is less than 200ms. In this case, the advertised interval is ( MaxRtrAdvInterval + 20ms ).

Default: off

AdvCaptivePortalAPI "URL"

When set, advertise RFC8908 Captive-Portal API URL.

See RFC8952 Captive Portal Architecture, RFC8910 Captive-Portal Identification in DHCP and Router Advertisements (RAs) and RFC8908 Captive Portal API for more information.

Most likely you do not need this.

Default: not included

## PREFIX SPECIFIC OPTIONS
AdvOnLink on|off

When set, indicates that this prefix can be used for on-link determination. When not set the advertisement makes no statement about on-link or off-link properties of the prefix. For instance, the prefix might be used for address configuration with some of the addresses belonging to the prefix being on-link and others being off-link.

Default: on

AdvAutonomous on|off

When set, indicates that this prefix can be used for autonomous address configuration as specified in RFC 4862.

Default: on

AdvRouterAddr on|off

When set, indicates that the address of interface is sent instead of network prefix, as is required by Mobile IPv6. When set, minimum limits specified by Mobile IPv6 are used for MinRtrAdvInterval and MaxRtrAdvInterval.

Default: off

AdvDHCPv6PDPreferred on|off

When set, indicates that the network prefers that clients use prefix delegation instead of acquiring individual addresses via SLAAC or DHCPv6 aaddress assignment.

See RFC 9762, "Using Router Advertisements to Signal the Availability of DHCPv6 Prefix Delegation to Clients"

Default: off

AdvValidLifetime seconds|infinity

The length of time in seconds (relative to the time the packet is sent) that the prefix is valid for the purpose of on-link determination. The symbolic value infinity represents infinity (i.e. a value of all one bits (0xffffffff)). The valid lifetime is also used by RFC 4862.

Note that clients will ignore AdvValidLifetime of an existing prefix if the lifetime is below two hours, as required in RFC 4862 Section 5.5.3 point e).

Note: RFC4861's suggested default value is significantly longer: 30 days.

Default: 86400 seconds (1 day)

AdvPreferredLifetime seconds|infinity

The length of time in seconds (relative to the time the packet is sent) that addresses generated from the prefix via stateless address autoconfiguration remain preferred. The symbolic value infinity represents infinity (i.e. a value of all one bits (0xffffffff)). See RFC 4862.

Note: RFC4861's suggested default value is significantly longer: 7 days.

Default: 14400 seconds (4 hours)

DeprecatePrefix on|off

Upon shutdown, this option will cause radvd to deprecate the prefix by announcing it in the radvd shutdown RA with a zero preferred lifetime and a valid lifetime slightly greater than 2 hours. This will encourage end-nodes using this prefix to deprecate any associated addresses immediately. Note that this option should only be used when only one router is announcing the prefix onto the link, otherwise end-nodes will deprecate associated addresses despite the prefix still being valid for preferred use.

See RFC4862, section 5.5.3., "Router Advertisement Processing", part (e).

Default: off

DecrementLifetimes on|off

This option causes radvd to decrement the values of the preferred and valid lifetimes for the prefix over time. The lifetimes are decremented by the number of seconds since the last RA. If radvd receives a SIGUSR1 signal, it will reset the values of the preferred and valid lifetimes back to the initial values used by radvd when it started. If radvd never receives a SIGUSR1 signal, it will continue to decrement the lifetimes until the preferred lifetime reaches zero. After a final RA with a zero value preferred lifetime, radvd will cease to announce the prefix. If a SIGUSR1 signal then causes the lifetimes to be reset, the prefix will then re-appear in the RAs.

This option is intended to be used in conjunction with a DHCPv6 client that is using the Identity Association for Prefix Delegation (IA_PD) option to acquire a prefix from a Delegating Router for use by a Requesting Router. In this scenario, the prefix(es) from within the delegated prefix that are announced by radvd would age in parallel with and at the same rate as the delegated prefix, and expire at approximately the same time, if the delegated prefix's life isn't extended.

See RFC3633, "IPv6 Prefix Options for Dynamic Host Configuration Protocol (DHCP) version 6".

Default: off

Base6Interface name

If this options is specified, this prefix will be combined with the IPv6 address of the interface specified by name. The resulting prefix length will be 64.

Base6to4Interface name

If this option is specified, this prefix will be combined with the IPv4 address of interface name to produce a valid 6to4 prefix. The first 16 bits of this prefix will be replaced by 2002 and the next 32 bits of this prefix will be replaced by the IPv4 address assigned to interface name at configuration time. The remaining 80 bits of the prefix (including the SLA ID) will be advertised as specified in the configuration file. See the next section for an example.

If interface name is not available at configuration time, a warning will be written to the log and this prefix will be disabled until radvd is reconfigured.

This option enables systems with dynamic IPv4 addresses to update their advertised 6to4 prefixes simply by restarting radvd or sending a SIGHUP signal to cause radvd to reconfigure itself.

Note that 6to4 prefixes derived from dynamically-assigned IPv4 addresses should be advertised with a significantly shorter lifetime (see the AdvValidLifetime and AdvPreferredLifetime options).

For more information on 6to4, see RFC 3056.

Default: 6to4 is not used

## ROUTE SPECIFIC OPTIONS
AdvRouteLifetime seconds|infinity

The lifetime associated with the route in units of seconds. The symbolic value infinity represents infinity (i.e. a value of all one bits (0xffffffff)).

Default: 3 * MaxRtrAdvInterval

AdvRoutePreference low|medium|high

The preference associated with the default router, as either "low", "medium", or "high".

Default: medium

RemoveRoute on|off

Upon shutdown, announce this route with a zero second lifetime. This should cause the route to be immediately removed from the receiving end-nodes' route table.

Default: on

## RDNSS SPECIFIC OPTIONS
AdvRDNSSLifetime seconds|infinity

The maximum duration how long the RDNSS entries are used for name resolution. A value of 0 means the nameserver must no longer be used. As described in RFC8106, the use of default value or a larger value ensures the reliability of an entry even under the loss of RAs on links with a relatively high rate of packet loss. Default: 3*MaxRtrAdvInterval

FlushRDNSS on|off

Upon shutdown, announce the RDNSS entries with a zero second lifetime. This should cause the RDNSS addresses to be immediately removed from the end-nodes' list of Recursive DNS Servers.

Default: on

## DNSSL SPECIFIC OPTIONS
AdvDNSSLLifetime seconds|infinity;

The maximum duration how long the DNSSL entries are used for name resolution. A value of 0 means the suffix should no longer be used. As described in RFC8106, the use of default value or a larger value ensures the reliability of an entry even under the loss of RAs on links with a relatively high rate of packet loss. Default: 3*MaxRtrAdvInterval

FlushDNSSL on|off

Upon shutdown, announce the DNSSL entries with a zero second lifetime. This should cause the DNSSL entries to be immediately removed from the end-nodes' DNS search list.

Default: on

## ABRO SPECIFIC OPTIONS
AdvValidLifetime seconds

The time in units of that the set of border router information is valid. A value of all zero bits assumes a default value of 10,000(~one week).

AdvVersionLow, AdvVersionHigh unsignedinteger

Both forms 32-bit unsigned version number corresponding to the set of information contained in RA message.

## NAT64 PREF64 SPECIFIC OPTIONS
AdvValidLifetime seconds

The length of time in seconds (relative to the time the packet is sent) that the prefix is valid for the purpose of NAT64 existence determination. In case the value is not a multiple of 8, the validity is rounded up to the next multiple of 8. The maximum is 65528 seconds.

Default: the lesser value of 3 * MaxRtrAdvInterval, or 65528

## EXAMPLES

```
interface eth0
{

        AdvSendAdvert on;

        prefix 2001:db8:0:1::/64

        {

                AdvOnLink on;

                AdvAutonomous on;

        };
};
```

It says that router advertisement daemon should advertise (AdvSendAdvert on;) the prefix 2001:db8:0:1:: which has a length of 64 on the interface eth0. Also the prefix should be marked as autonomous (AdvAutonomous on;) and as on-link (AdvOnLink on;). All the other options are left on their default values.

To support movement detection of Mobile IPv6 Mobile Nodes, the address of interface should be used instead of network prefix:

```
interface eth0
{

        AdvSendAdvert on;

        prefix 2001:db8:0:1::4/64

        {

                AdvOnLink on;

                AdvAutonomous on;

                AdvRouterAddr on;

        };
};
```

For 6to4 support, include the Base6to4Interface option in each prefix section. When using a dynamic IPv4 address, set small prefix lifetimes to prevent hosts from retaining unreachable prefixes after a new IPv4 address has been assigned. When advertising to on a dynamic interface (e.g., Bluetooth), skip the interface if it is not active yet.

```
interface bnep0
{

        IgnoreIfMissing on;

        AdvSendAdvert on;

        # Advertise at least every 30 seconds

        MaxRtrAdvInterval 30;

        prefix 0:0:0:5678::/64

        {

                AdvOnLink on;

                AdvAutonomous on;

                Base6to4Interface ppp0;

                # Very short lifetimes for dynamic addresses

                AdvValidLifetime 300;

                AdvPreferredLifetime 120;

        };
};
```

Since 6to4 is enabled, the prefix will be advertised as 2002:WWXX:YYZZ:5678::/64, where WW.XX.YY.ZZ is the IPv4 address of ppp0 at configuration time. (IPv6 addresses are written in hexadecimal whereas IPv4 addresses are written in decimal, so the IPv4 address WW.XX.YY.ZZ in the 6to4 prefix will be represented in hex.)

In this specific case, the configuration scripts may send HUP signal to radvd when taking bnep0 up or down to notify about the status; in the current radvd releases, sending HUP is no longer mandatory when the link comes back up.

```
interface eth0
{

        AdvSendAdvert on;

        prefix 2001:db8:0:1::/64

        {

                AdvOnLink on;

                AdvAutonomous on;

        };

        clients

        {

                fe80::21f:16ff:fe06:3aab;

                fe80::21d:72ff:fe96:aaff;

        };
};
```

This configuration would only announce the prefix to fe80::21f:16ff:fe06:3aab and fe80::21d:72ff:fe96:aaff. Furthermore, all RA requests of other clients are denied.

This may come in handy if you want to roll out IPv6 only partially because some clients are broken or untested.

For ABRO support

```
interface lowpan0
{
	AdvSendAdvert on;
	UnicastOnly on;
	AdvCurHopLimit 255;
	prefix 2001:0db8:0100:f101::/64 {
		AdvOnLink on;
		AdvAutonomous on;
		AdvRouterAddr on;
	};
	abro fe80::a200:0:0:1/64 {
		AdvVersionLow 10;
		AdvVersionHigh 2;
		AdvValidLifetime 2;
	};
};
The NAT64 pref64 support

interface eth0
{
	prefix 2001:db8:100::/64 {
		AdvOnLink on;
		AdvAutonomous on;
		AdvRouterAddr on;
	};
	nat64prefix 64:ff9b::/96 {
		AdvValidLifetime 1800;
	};
	RDNSS 2001:db8:100::64 {
		AdvRDNSSLifetime 1800;
	};
};
```

## FILES

```
/usr/sbin/radvd
/etc/radvd.conf
/run/radvd/radvd.pid
/var/log/radvd.log
```

## CREDIT
The description of the different flags and variables is in large parts taken from RFC 4861.

## RFCS
Narten, T., Nordmark, E., Simpson, W., and H. Soliman, "Neighbor Discovery for IP Version 6 (IPv6)", RFC 4861, September 2007.

Thomson, S., Narten, T., T. Jinmei, "IPv6 Stateless Address Autoconfiguration", RFC 4862, September 2007.

Deering, S., and R. Hinden, "IP Version 6 Addressing Architecture", RFC 4291, February 2006.

Conta, A., Deering, S., and M. Gupta "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6)", RFC 4443, March 2006.

Crawford, M., "Transmission of IPv6 Packets over Ethernet Networks", RFC 2464, December 1998.

Carpenter B., K. Moore, "Connection of IPv6 Domains via IPv4 Clouds", RFC 3056, February 2001. (6to4 specification)

Draves, R., D. Thaler, "Default Router Preferences and More-Specific Routes", RFC 4191, November 2005.

Johnson, D., Perkins, C., and J. Arkko, "Mobility Support in IPv6", RFC 3775, June 2004.

Devarapalli, V., Wakikawa, R., Petrescu, A., and P. Thubert "Network Mobility (NEMO) Basic Support Protocol", RFC 3963, January 2005.

Z. Shelby, S. Chakrabarti, E. Nordmark and C. Bormann " Neighbor Discovery Optimization for IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs)", RFC 6775, November 2012.

Gont, F. "Security Implications of IPv6 Fragmentation with IPv6 Neighbor Discovery", RFC 6980, August 2013.

Yourtchenko, A. and Colitti, L. "Reducing Energy Consumption of Router Advertisements", RFC 7772, February 2016.

J. Jeong, S. Park, L. Beloeil, and S. Madanapalli, "IPv6 Router Advertisement Options for DNS Configuration", RFC 8106, March 2017.

L. Colitti, and J. Linkova, "Discovering PREF64 in Router Advertisements", RFC 8781, April 2020.

## SEE ALSO
radvd(8), radvdump(8)

## AUTHORS

```
See radvd.8 manpage for authors
```


cloginrc

package: rancid

title: cloginrc(5)

summary: clogin configuration file

text:
# cloginrc(5)

## NAME

.cloginrc - clogin configuration file

## DESCRIPTION
.cloginrc contains configuration information for alogin(1), blogin(1), clogin(1), elogin(1), flogin(1), hlogin(1), htlogin(1), jlogin(1), nlogin(1), nslogin(1), rivlogin(1), and tntlogin(1), such as usernames, passwords, ssh encryption type, etc., and is read at run-time.

Each line contains either white-space (blank line), a comment which begins with the comment character '#' and may be preceded by white-space, or one of the directives listed below.

Each line containing a directive is of the form:

```
add <directive> <hostname glob> {<value>} [{<value>} ...]

or

include {<file>}
```

Note: the braces ({}) surrounding the values is significant when the values include TCL meta-characters. Best common practice is to always enclose the values in braces. If a value includes a (left or right) brace or space character, it must be backslash-escaped, as in:

```
add user <hostname glob> {foo\}bar}
add user <hostname glob> {foo\ bar}
```

As .cloginrc is searched for a directive matching a hostname, it is always the first matching instance of a directive, one whose hostname glob expression matches the hostname, which is used. For example; looking up the "password" directive for hostname foo in a .cloginrc file containing

```
add password *   {bar} {table}
add password foo {bar} {table}
```

would return the first line, even though the second is an exact match.

.cloginrc is expected to exist in the user's home directory and must not be readable, writable, or executable by "others". .cloginrc should be mode 0600, or 0640 if it is to be shared with other users who are members of the same unix group. See chgrp(1) and chmod(1) for more information on ownership and file modes.

## DIRECTIVES
The accepted directives are (alphabetically):

add autoenable <router name glob> {[01]}

When using locally defined usernames or AAA, it is possible to have a login which is automatically enabled. This is, that user has enable privileges without the need to execute the enable command. The router's prompt is different for enabled mode, ending with a # rather than a >. Example: add autoenable * {1}

Default: 0

zero, meaning that the user is not automatically enabled and clogin should execute the enable command to gain enable privileges, unless negated by the noenable directive or -noenable command-line option.

Also see the noenable directive.

add cyphertype <router name glob> {<ssh encryption type>}

cyphertype defines which encryption algorithm is used with ssh. A device may not support the type ssh uses by default. See ssh(1)'s -c option for details. Default: {3des}

add enableprompt <router name glob> {"<enable prompt>"}

When using AAA with a Cisco router or switch, it is possible to redefine the prompt the device presents to the user for the enable password. enableprompt may be used to adjust the prompt that clogin should look for when trying to login. Note that enableprompt can be a Tcl style regular expression. Example: add enableprompt rc*.example.net {"\[Ee]nter\ the\ enable\ password:"}

Default: "\[Pp]assword:"

add enauser <router name glob> {<username>}

This is only needed if a device prompts for a username when gaining enable privileges and where this username is different from that defined by or the default of the user directive.

add identity <router name glob> {<ssh identity file path>}

May be used to specify an alternate identity file for use with ssh(1). See ssh's -i option for details. Default: your default identity file. see ssh(1).

add method <router name glob> {ssh} [{...}]

Defines, in order, the connection methods to use for a device from the set {ssh, telnet, rsh}. Method telnet may have a suffix, indicating an alternate TCP port, of the form ":port". Note: Different versions of telnet treat the specification of a port differently. In particular, BSD derived telnets do not do option negotiation when a port is given. Some devices, Extreme switches for example, have undesirable telnet default options such as linemode. In the BSD case, to enable option negotiation when specifying a port the method should be "{telnet:-23}" or you should add "mode character" to .telnetrc. See telnet(1) for more information on telnet command-line syntax, telnet options, and .telnetrc.

Example: add method * {ssh} {telnet:-3000} {rsh}

Which would cause clogin to first attempt an ssh connection to the device and if that were to fail with connection refused, a telnet connection to port 3000 would be tried, and then a rsh connection.

Note that not all platforms support all of these connection methods.

Default: {telnet} {ssh}

add noenable <router name glob> {1}

clogin will not try to gain enable privileges when noenable is matched for a device. This is equivalent to clogin's -noenable command-line option. Note that this directive is meaningless for jlogin(1), nlogin(1) and clogin(1) [for Extreme] which do not have the concept of "enabled" and/or no way to elevate privleges once logged in; a user either has the necessary privleges or doesn't.

add passphrase <router name glob> {"<SSH passphrase>"}

Specify the SSH passphrase. Note that this may be particular to an identity directive. The passphrase will default to the password for the given router. Example: add passphrase rc*.example.net {the\ bird\ goes\ tweet}

add passprompt <router name glob> {"<password prompt>"}

When using AAA with a Cisco router or switch, it is possible to redefine the prompt the device presents to the user for the password. passprompt may be used to adjust the prompt that clogin should look for when trying to login. Note that passprompt can be a Tcl style regular expression. Example: add passprompt rc*.example.net {"\[Ee]nter\ the\ password:"}

Default: "(\[Pp]assword|passwd):"

add password <router name glob> {<vty passwd>} [{<enable passwd>}]

Specifies a vty password, that which is prompted for upon the connection to the router. The last argument is the enable password and need not be specified if the device also has a matching noenable or autoenable directive or the corresponding command-line options are used.

add sshcmd <router name glob> {<ssh>}

<ssh> is the name of the ssh executable. OpenSSH uses a command-line option to specify the protocol version, but other implementations use a separate binary such as "ssh1". sshcmd allows this to be adjusted as necessary for the local environment. Default: ssh

add timeout <router name glob> {<seconds>}

Time in seconds that the login script will wait for input from the device before timeout. Default: device dependent

add user <router name glob> {<username>}

Specifies a username clogin should use if or when prompted for one. Default: $USER (or $LOGNAME), i.e.: your Unix username.

add userpassword <router name glob> {<user password>}

Specifies a password to be associated with a user, if different from that defined with the password directive.

add userprompt <router name glob> {"<username prompt>"}

When using AAA with a Cisco router or switch, it is possible to redefine the prompt the device presents to the user for the username. userprompt may be used to adjust the prompt that clogin should look for when trying to login. Note that userprompt can be a Tcl style regular expression. Example: add userprompt rc*.example.net {"\[Ee]nter\ your\ username:"}

Default: "(Username|login|user name):"

include {<file>}

<file> is the pathname of an additional .cloginrc file to include at that point. It is evaluated immediately. That is important with regard to the order of matching hostnames for a given directive, as mentioned above. This is useful if you have your own .cloginrc plus an additional .cloginrc file that is shared among a group of folks. If <file> is not a full pathname, $HOME/ will be prepended.

Example: include {.cloginrc.group}

## FILES

```
$HOME/.cloginrc               Configuration file described here.
share/rancid/cloginrc.sample  A sample .cloginrc.
```

## ERRORS
.cloginrc is interpreted directly by Tcl, so its syntax follows that of Tcl. Errors may produce quite unexpected results.

## SEE ALSO
clogin(1), glob(3), tclsh(1)


lg.conf

title: lg.conf(5)

summary: looking glass configuration file

text:
# lg.conf(5)

## NAME
lg.conf - looking glass configuration file

## DESCRIPTION
lg.conf contains configuration for the looking glass scripts.

The syntax is that of perl(1). It is used to set variables that affect run-time behavior and/or to locate resources.

## VARIABLES
The following variables are used (alphabetically):

LG_AS_REG

*** not implemented.

LG_BGP_RT

Allows show ip bgp neighbor commands that can produce heavy output, such as sh ip bgp neighbor <ip> advertised-routes for a transit customer when the neighbor address is followed by 'advertised-routes' for the sh ip bgp neighbor query.

LG_CACHE_DIR

Sets the location of the cache directory. The looking glass uses this to hold lock files, log files, and output from cached commands. Default: ./tmp

Note that the default is relative to the directory where lg.cgi runs in the server's document root (e.g.: /usr/local/www/data/lg/tmp).

LG_CACHE_TIME

Sets the number of seconds that the looking glass should cache output from commands that tend to produce a lot of output, such as 'show ip bgp dampened-paths'. Default: 600

LG_CLOGINRC

Defines the location of the cloginrc(5) that the looking glass should use. The path may be relative to the directory where the CGI scripts run in the server's document root. Default: $HOME/.cloginrc

Note that the .cloginrc must be readable by the user or group that will be running the CGI and that clogin(1) will not allow a world readable .cloginrc. The user is normally that of the http server (httpd).

LG_IMAGE

Defines a html image tag () which, if defined, will be included at the top of the looking glass pages. It may contain any html as it is simply handed off to print(). Example: $LG_IMAGE="\n FOO";

LG_INFO

Defines information in html format which, if defined, will be included at the bottom of the looking glass form page. It may contain any html as it is simply handed off to print(). Example: $LG_INFO="For Support contact webmaster";

LG_LOG

Defines the fully qualified path name (i.e.: begins with '/') for the log file or the syslog(3) facility to use for logging. For syslog, the argument is the lowercase name of a syslog facility (see syslog.h) without the 'LOG_' prefix. Example: local0

Default: $LG_CACHE_DIR/lg.log

LG_ROUTERDB

Sets the location for the router.db file in rancid's router.db(5) format. It lists the devices that should be available to the looking glass users. Only those devices of supported types and with state 'up' are made available. If not defined and the default file does not exist, the looking glass will compile a list from the router.db files of all the groups present in rancid, that is, the list will be a concatenation of the available router.db(5) files. Note that if the concatenation method is used, it may be necessary to alter the mode of the router.db files in the rancid group directories, since rancid's default umask is 027 (see rancid.conf(5)).

LG_STRIP

Causes the LG to strip login information from the looking glass results. Since Expect often munges disabling echo when passwords are entered, this is a SECURITY CONCERN! However, this output can be very useful for debugging clogin problems.

LG_STYLE

Defines the URL of a style sheet to be used for HTML formatting.

PATH

Is a colon separated list of directory pathnames in the file system where rancid's login scripts, clogin(1) etc.) and programs needed within these, such as telnet(1), are located. Its value is set by configure. Should it be necessary to modify PATH, note that it must include $BASEDIR/bin (see above).

Queries ...................................

## ENVIRONMENT
LG_CONF

Location of lg.conf file. See the FILES section for more information.

## ERRORS
lg.conf is interpreted directly by perl(1), so its syntax follows that of perl. Syntax errors may produce quite unexpected results.

## FILES
/etc/rancid/lg.conf

Configuration file described here. lg.conf is located by the value of the environment variable LG_CONF, in the CWD (current working directory), or the sysconfdir defined when rancid was installed, in that order.

## SEE ALSO
cloginrc(5), lg_intro(1), router.db(5)

## HISTORY
In RANCID releases prior to 2.3, lg.conf was located in the util/lg sub-directory of the install path. This was changed to be more consistent with common file location practices.


rancid.conf

title: rancid.conf(5)

summary: rancid environment configuration file

text:
# rancid.conf(5)

## NAME
rancid.conf - rancid environment configuration file

## DESCRIPTION
rancid.conf contains environment configuration information for rancid-run(1) and rancid-cvs(1), including shell PATH, list of rancid groups, etc. It is read by several scripts at run-time and others inherit the configration from a parent process which has read it.

The syntax of rancid.conf is that of sh(1). rancid.conf is used to set environment variables used by other rancid scripts to effect their run-time behavior or to enable them to find their resources.

## VARIABLES
The following variables are used (listed alphabetically):

ACLSORT

Permits disabling of access-list sorting, which could alter statement order that had been cleverly crafted by the administrator for optimal performance, thus making recovery and comparsion more difficult. Default: YES

BASEDIR

BASEDIR is the directory where rancid-run's log directory, the revision control system's repository, and rancid group directories will be placed. Its value is configure's localstatedir and should be modified if rancid is moved to a new location in the file system without re-installing from the distribution.

Default: /var/lib

CVSROOT

cvs(1) and rancid-cvs(1) use this environment variable to locate the CVS repository. In some cases, and for Subversion, it is used as an argument to commands. It should not be necessary to alter it. Default: $BASEDIR/CVS

FILTER_PWDS

Determines which passwords will be filtered from configs. The value may be "NO", "YES", or "ALL" to filter none of the passwords, only those which are reversable or plain-text, or all (plus ssh keys, etc), respectively. Default: YES

Note: a value of "NO" could be a security issue since diffs are sent via e-mail. A value of "ALL" is encouraged.

Note: FILTER_PWDS does not affect the handling of SNMP community strings. see NOCOMMSTR below.

Note: passwords whose value cycles and would produce erroneous diffs are always filtered (e.g.: Alteon passwords).

LIST_OF_GROUPS

Defines a list of group names of routers separated by white-space. These names become the directory names in $BASEDIR which contain the data for that set of devices. rancid-run(1) also uses this variable to determine which device groups it should collect. Choose these names to be descriptive of the set of devices and do not use spaces, unprintable characters, etc. Example: LIST_OF_GROUPS="UofO USFS"

Two groups are defined; UofO (University of Oregon) and USFS (US Forest Service). Each will have a directory created (see rancid-cvs(1)) $BASEDIR/UofO and $BASEDIR/USFS respectively, which will contain their data.

Each group must also have aliases for the administrative and diff recipients set-up in /etc/aliases. For example:

```
rancid-uofo:            frank
rancid-admin-uofo:      joe,bob
rancid-usfs:            frank
rancid-admin-usfs:      joe,bob
```

LOCKTIME

Defines the number of hours a group's lock file may age before rancid starts to complain about a hung collection. The default is 4 hours.

LOGDIR

Directory where rancid-run places log files. Default: $BASEDIR/logs

MAILDOMAIN

Define the domain part of addresses for administrative and diff e-mail. The value of this variable is simply appended to the normal mail addresses. For example rancid-usfs@example.com, if MAILDOMAIN had been set to "@example.com".

MAILHEADERS

Define additional mail headers to be added to rancid mail, such as Precedence or X- style headers. Individual headers must be separated by a \n (new line). Default: Precedence: bulk

Example: Precedence: bulk\nX-clamation: beef cake

MAX_ROUNDS

Defines how many times rancid should retry collection of devices that fail. The minimum is 1. Default: 4.

NOCOMMSTR

If set, rancid(1) will filter SNMP community strings from configs. Otherwise, they will be retained and may appear in clear-text in e-mail diffs. By default, this is not set.

NOPIPE

If set, rancid(1) will use temporary files to save the output from the router and then read these to build the file which will be saved in CVS (or Subversion). Otherwise, an IPC pipe will be used. We have found that the buffering mechanisms used in perl and expect are heinous. Using temporary files may result in a noticeable improvement in speed. By default, this is not set.

OLDTIME

Specified as a number of hours, OLDTIME defines how many hours should pass since a successful collection of a device's configuration and when control_rancid(1) should start complaining about failures. The value should be greater than the number of hours between rancid-run cron runs. Default: 24

PAR_COUNT

Defines the number of rancid processes that par(1) will start simultaneously as control_rancid(1) attempts to perform collections. Raising this value will decrease the amount of time necessary for a complete collection of a (or all) rancid groups at the expense of system load. The default is relatively cautious. If collections are not completing quickly enough for users, use trial and error of speed versus system load to find a suitable value. Default: 5

PATH

Is a colon separate list of directory pathnames in the the file system where rancid's sh(1) and perl(1) scripts should look for the programs that it needs, such as telnet(1). Its value is set by configure. Should it be necessary to modify PATH, note that it must include /usr/lib/rancid.

RCSSYS

Sets which revision control system is in use. Valid values are cvs for CVS or svn for Subversion. Default: cvs

TERM

Some Unix utilities require TERM, the terminal type, to be set to a sane value. Some clients, such as telnet(1) and ssh(1), communicate this to the server (i.e.: the remote device), thus this can affect the behavior of login sessions on a device. The default should suffice. Default: network

TMPDIR

Some Unix utilities recognize TMPDIR as a directory where temporary files can be stored. In some cases, rancid utilizes this directory for lock files and other temporary files. Default: /tmp

Each of these are simply environment variables. In order for them to be present in the environment of child processes, each must be exported. See sh(1) for more information on the built-in command export.

## ERRORS
rancid.conf is interpreted directly by sh(1), so its syntax follows that of the bourne shell. Errors may produce quite unexpected results.

## FILES
/etc/rancid/rancid.conf

Configuration file described here.

## SEE ALSO
control_rancid(1), rancid(1), rancid-cvs(1), rancid-run(1)

## HISTORY
In RANCID releases prior to 2.3, rancid.conf was named env and located in the bin directory. This was changed to be more consistent with common file location practices.


router.db

title: router.db(5)

summary: rancid group configuration file

text:
# router.db(5)

## NAME
router.db - rancid group configuration file

## DESCRIPTION
router.db contains information for devices which are members of a rancid group. control_rancid(1) reads this file to compile a list of devices which it should collect.

## SYNTAX
One device is listed per-line, where the syntax is:

```
<device_name>:<device_type>:<state>[:comments]
```

For example:

```
scooby.shrubbery.net:cisco:up
```

The fields are as follows:

<device_name>

The name of the device, which must resolve via gethostbyname, used as the argument to telnet(1), rsh(1), or ssh(1), to connect to the device. Once converted to lower-case, this also becomes the name of the file used to store the configuration under $BASEDIR/<group>/configs. Experience has shown that using the device's FQDN (Fully Qualified Domain Name) works best, as in the example above.

<device_type>

The type of device from the set:

agm

A Cisco Anomoly Guard Module (aka Riverhead). Suspect that at some point the UI will become more cisco-like and it can be merged with the IOS rancid module.

alteon

An Alteon WebOS switches.

arista

An Arista Networks device.

avocent

An Avocent Cyclades console server.

baynet

A Bay Networks router.

cat5

A Cisco catalyst series 5000 and 4000 switches (i.e.: running the catalyst OS, not IOS).

cisco

A Cisco router, PIX, or switch such as the 3500XL or 6000 running IOS (or IOS-like) OS, but not IOS-XR.

cisco-nx

A Cisco Nexus switch/router.

cisco-xr

A Cisco device running IOS-XR.

css

A Cisco content services switch.

enterasys

An enterasys NAS. This is currently an alias for the riverstone device type.

erx

A Juniper E-series edge router.

extreme

An Extreme switch.

ezt3

An ADC-Kentrox EZ-T3 mux.

f5

A F5 BigIP switch.

force10

A Force10 router.

fortigate

A Fortinet firewall.

foundry

A Foundry router, switch, or router-switch. This includes HP Procurve switches that are OEMs of Foundry products, such as the HP9304M.

hitachi

A Hitachi router.

hp

A HP Procurve switch such as the 2524 or 4108 procurve switches. Also see the foundry type.

juniper

A Juniper router.

mikrotik

A Mikrotik router.

mrtd

A host running the (Merit) MRTd daemon.

netscalar

A Netscalar load balancer.

netscreen

A Netscreen firewall.

procket

A Procket router.

redback

A Redback router, NAS, etc.

riverstone

A Riverstone NAS or Cabletron (starting with version ~9.0.3) router.

smc

A SMC switch (some Dell OEMs).

tnt

A Lucent TNT.

zebra

Zebra routing software.

<state>

The state is either "up", or some other arbitrary value, e.g. "down". If the device is not marked "up" the device's configuration will not be collected. It is highly recommended that comments are made for any router not listed as up, so as to indicate the reason a router is not to be polled, e.g.: dial1.paris:cisco:up:

core1.paris:cisco:down:in testing until 5/5/2001.

core2.paris:cisco:ticketed:Ticket 6054234, 5/3/2001

border1.paris:juniper:up:

The script "downreport" in util/ can be used to produce a report of routers in router.db that are not marked "up".

[comments]

Freeform string to describe the current state of the router.

A ``#'' at the begining of a line is a comment; the entire line is ignored.

If a device is deleted from the router.db file, then rancid will clean up by removing the device's config file from $BASEDIR/<group>/configs. The device will be removed from the revision control system. It is possible, in most cases, to resurrect or check-out copies of deleted device configurations.

## FILES
$BASEDIR/<group>/router.db

Configuration file described here, where <group> is a device group name defined in the variable LIST_OF_GROUPS within $BASEDIR/etc/rancid.conf.

## SEE ALSO
control_rancid(1), rancid(1), rancid.conf(5)