oxidized 0.30.1 → 0.32.0

data/docs/Configuration.md

@@ -9,7 +9,7 @@ The following example will log an active ssh/telnet session `/home/oxidized/.con
 ```yaml
 log: /home/oxidized/.config/oxidized/log
 
-...
+# ...
 
 input:
   default: ssh, telnet
@@ -45,7 +45,7 @@ As a partial example from ios.rb:
 ```ruby
   cmd :secret do |cfg|
     cfg.gsub! /^(snmp-server community).*/, '\\1 <configuration removed>'
-    (...)
+    # ...
     cfg
   end
 ```
@@ -98,14 +98,14 @@ vars:
 Per-Node:
 
 ```yaml
-...
+# ...
 map:
   name: 0
   model: 1
 vars_map:
   enable: 2
   ssh_keys: 3
-...
+# ...
 ```
 
 If you are using a non-standard path, especially when copying the private key via a secured channel, make sure that the permissions are set correctly:
@@ -131,7 +131,7 @@ This can be provided on a per-node basis by mapping the proper fields from your
 An example for a `csv` input source that maps the 4th field as the `ssh_proxy` value and the 5th field as `ssh_proxy_port`.
 
 ```yaml
-...
+# ...
 map:
   name: 0
   model: 1
@@ -139,7 +139,7 @@ vars_map:
   enable: 2
   ssh_proxy: 3
   ssh_proxy_port: 4
-...
+# ...
 ```
 
 ## SSH enabling legacy algorithms
@@ -149,7 +149,7 @@ When connecting to older firmware over SSH, it is sometimes necessary to enable
 These settings can be provided on a per-node basis by mapping the ssh_kex, ssh_host_key, ssh_hmac and the ssh_encryption fields from you source.
 
 ```yaml
-...
+# ...
 map:
   name: 0
   model: 1
@@ -159,7 +159,7 @@ vars_map:
   ssh_host_key: 4
   ssh_hmac: 5
   ssh_encryption: 6
-...
+# ...
 ```
 
 ## FTP Passive Mode
@@ -174,7 +174,16 @@ input:
 
 ## Advanced Configuration
 
-Below is an advanced example configuration. You will be able to (optionally) override options per device. The router.db format used is `hostname:model:username:password:enable_password`. Hostname and model will be the only required options, all others override the global configuration sections.
+Below is an advanced example configuration.
+
+You will be able to (optionally) override options per device.
+The router.db format used is `hostname:model:username:password:enable_password`.
+Hostname and model will be the only required options, all others override the
+global configuration sections.
+
+Custom model names can be mapped to an oxidized model name with a string or
+a regular expression.
+
 
 ```yaml
 ---
@@ -226,6 +235,7 @@ source:
 model_map:
   cisco: ios
   juniper: junos
+  !ruby/regexp /procurve/: procurve
 ```
 
 ## Advanced Group Configuration
@@ -242,13 +252,15 @@ groups:
     password: ubnt
 ```
 
-Model specific variables within groups
+Model specific variables/credentials within groups
 
 ```yaml
 groups:
   foo:
     models:
       arista:
+        username: admin
+        password: password
         vars:
           ssh_keys: "~/.ssh/id_rsa_foo_arista"
       vyatta:
@@ -260,11 +272,14 @@ groups:
         vars:
           ssh_keys: "~/.ssh/id_rsa_bar_routeros"
       vyatta:
+        username: admin
+        password: pass
         vars:
           ssh_keys: "~/.ssh/id_rsa_bar_vyatta"
 ```
 
-For mapping multiple group values to a common name
+For mapping multiple group values to a common name, you can use strings and
+regular expressions:
 
 ```yaml
 group_map:
@@ -272,17 +287,18 @@ group_map:
   alias2: groupA
   alias3: groupB
   alias4: groupB
+  !ruby/regexp /specialgroup/: groupS
   aliasN: groupZ
-  ...
+  # ...
 ```
 
 add group mapping to a source
 
 ```yaml
 source:
-  ...
+  # ...
   <source>:
-    ...
+    # ...
     map:
       model: 0
       name: 1
@@ -311,15 +327,35 @@ models:
     password: pass
 ```
 
+### Options (credentials, vars, etc.) precedence:
+From least to most important:
+- global options
+- model specific options
+- group specific options
+- model specific options in groups
+- options defined on single nodes
+
+More important options overwrite less important ones if they are set.
+
 ## RESTful API and Web Interface
 
 The RESTful API and Web Interface is enabled by configuring the `rest:` parameter in the config file.  This parameter can optionally contain a relative URI.
 
+```yaml
+# Listen on http://[::1]:8888/
+rest: "[::1]:8888"
+```
+
 ```yaml
 # Listen on http://127.0.0.1:8888/
 rest: 127.0.0.1:8888
 ```
 
+```yaml
+# Listen on http://[2001:db8:0:face:b001:0:dead:beaf]:8888/oxidized/
+rest: "[2001:db8:0:face:b001:0:dead:beaf]:8888"
+```
+
 ```yaml
 # Listen on http://10.0.0.1:8000/oxidized/
 rest: 10.0.0.1:8000/oxidized

data/docs/Creating-Models.md

@@ -6,6 +6,14 @@ A user may wish to extend an existing model to collect the output of additional
 
 This methodology allows local site changes to be preserved during Oxidized version updates / gem updates. It also enables convenient local development of new models.
 
+## Index
+- [Creating a new model](#creating-a-new-model)
+- [Extending an existing model with a new command](#extending-an-existing-model-with-a-new-command)
+- [Create unit tests for the model](#create-unit-tests-for-the-model)
+- [Advanced features](#advanced-features)
+- [Monkey-patching blocks in existing models](#monkey-patching-blocks-in-existing-models)
+- [Help](#help)
+
 ## Creating a new model
 
 An Oxidized model, at minimum, requires just three elements:
@@ -21,13 +29,19 @@ class RootWare < Oxidized::Model
   using Refinements
   
   cmd 'show complete-config'
+
+  cfg :ssh do
+    pre_logout 'exit'
+  end
+end
 ```
 
 This model, as-is will:
 
-* Log into the device and expect the default prompt.
+* Log into the device with ssh and expect the default prompt.
 * Upon matching it, execute the command `show complete-config`
 * Collect the output.
+* Logout with the command `exit`
 
 It is often useful to, at minimum, define the following additional elements for any newly introduced module:
 
@@ -40,6 +54,52 @@ The API documentation contains a list of [methods](https://github.com/ytti/oxidi
 
 A more fleshed out example can be found in the `IOS` and `JunOS` models.
 
+### Common task: mechanism for handling 'enable' mode
+The following code snippet demonstrates how to handle sending the 'enable'
+command and an enable password.
+
+This example is taken from the `IOS` model. It covers scenarios where users
+need to enable privileged mode, either without providing a password (by setting
+`enable: true` in the configuration) or with a password.
+
+```ruby
+  cfg :telnet, :ssh do
+    post_login do
+      if vars(:enable) == true
+        cmd "enable"
+      elsif vars(:enable)
+        cmd "enable", /^[pP]assword:/
+        cmd vars(:enable)
+      end
+    end
+  end
+```
+Note: remove `:telnet, ` if your device does not support telnet.
+
+### Common Task: remove ANSI escape codes
+> :warning: This common task is experimental.
+> If it does not work for you, please open an issue so that we can adapt the
+> code snippet.
+
+Some devices produce ANSI escape codes to enhance the appearance of output.
+However, this can make prompt matching difficult and some of these ANSI escape
+codes might end up in the resulting configuration.
+
+You can remove most [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Control_Sequence_Introducer_commands) using the following Ruby
+code in your model:
+```
+  # Remove ANSI escape codes
+  expect /\e\[[0-?]*[ -\/]*[@-~]\r?/ do |data, re|
+    data.gsub re, ''
+  end
+```
+Explanation of the Regular Expression:
+- `\e\[`   : Control Sequence Introducer (CSI), which starts with "ESC [".
+- `[0-?]*` : "Parameter" bytes (range 0x30–0x3F, corresponding to ASCII `0–9:;<=>?`).
+- `[ -\/]*`: "Intermediate" bytes (range 0x20–0x2F, corresponding to ASCII ` !"#$%&'()*+,-./`).
+- `[@-~]`  : The "final" byte (range 0x40–0x7E, corresponding to ASCII ``@A–Z[\]^_`a–z{|}~).[``).
+- `\r?`    : Some ESC codes include a carriage return, which we do not want in the resulting config.
+
 ## Extending an existing model with a new command
 
 The example below can be used to extend the `JunOS` model to collect the output of `show interfaces diagnostics optics` and append the output to the configuration file as a comment. This command retrieves DOM information on pluggable optics present in a `JunOS`-powered chassis.
@@ -72,6 +132,17 @@ Intuitively, it is also possible to:
 * Create a completely new model, with a new name, for a new operating system type.
 * Testing/validation of an updated model from the [Oxidized GitHub repo models](https://github.com/ytti/oxidized/tree/master/lib/oxidized/model) by placing an updated model in the proper location without disrupting the gem-supplied model files.
 
+## Create Unit Tests for the Model
+If you want the model to be integrated into Oxidized, you can
+[submit a pull request on GitHub](https://github.com/ytti/oxidized/pulls).
+This is a greatly appreciated submission, as there are probably other users
+using the same network device as you are.
+
+A good (and optional) practice for submissions is to provide a
+[unit test for your model](/docs/ModelUnitTests.md). This reduces the risk that
+further developments could break it, and facilitates debugging issues without
+having access to a physical network device for the model.
+
 ## Advanced features
 
 The loosely-coupled architecture of Oxidized allows for easy extensibility in more advanced use cases as well.
@@ -124,19 +195,19 @@ Examples:
 
 ```ruby
 cmd :secret, clear: true do
-  ... "(new code for secret removal which replaces the existing :secret definition in the model)" ...
+  # ... "(new code for secret removal which replaces the existing :secret definition in the model)" ...
 end
 ```
 
 ```ruby
 cmd 'show version', clear: true do |cfg|
-  ... "(new code for parsing 'show version', replaces the existing definition in the model)" ...
+  # ... "(new code for parsing 'show version', replaces the existing definition in the model)" ...
 end
 ```
 
 ```ruby
 cmd :ssh, prepend: true do
-  ... "(code that should run first, before any code in the existing :ssh definition in the model)" ...
+  # ... "(code that should run first, before any code in the existing :ssh definition in the model)" ...
 end
 ```
 

data/docs/DeviceSimulation.md

@@ -0,0 +1,184 @@
+# Device Simulation
+Oxidized supports [150+ devices](/docs/Supported-OS-Types.md).
+
+No developer has access to all of these devices, which makes the task of
+maintaining Oxidized difficult:
+
+- Issues can't be resolved because the developer has no access to the device.
+- Further developments can produce regressions.
+
+In order to address this, we can simulate the devices. An example of a
+simulation is the [model unit tests](/spec/model), but one could also simulate a
+device within an SSH server.
+
+The simulation of devices is currently focused on SSH-based devices. This may be
+extended to other inputs like Telnet or FTP in the future.
+
+## YAML Simulation Data
+The underlying data for the simulation is a [YAML](https://yaml.org/) file in
+which we store all relevant information about the device. The most important
+information is the responses to the commands used in the Oxidized models.
+
+The YAML simulation files are stored under
+[/spec/model/data/](/spec/model/data/), with the naming convention
+`<model>:<description>:simulation.yaml`, where `<model>` is the lowercase name
+of the Oxidized model and `<description>` is the name of the test case.
+`<description>` is generally formatted as `<hardware>_<software>` or
+`<hardware>_<software>_<information>`.
+
+### Creating a YAML Simulation File with device2yaml.rb
+A device does not only output the ASCII text we can see in the console.
+It adds ANSI escape codes for nice colors, bold and underline, \r, and so on.
+These are key factors in prompt issues, so they must be represented in the YAML
+file. We use the Ruby string format with interpolations like \r, \e, and so on.
+Another important point is trailing spaces at the end of lines. Some text
+editors automatically remove trailing spaces, so we code them with \x20.
+
+Although a YAML file could be written by hand, this is quite a tedious task to
+catch all the extra codes and code them into YAML. This can be automated with
+the Ruby script [extra/device2yaml.rb](/extra/device2yaml.rb).
+
+`device2yaml.rb` needs Ruby and the gem
+[net-ssh](https://rubygems.org/gems/net-ssh/) to run. On Debian, you can install
+them with `sudo apt install ruby-net-ssh`.
+
+Run `extra/device2yaml.rb`, the online help tells you the options.
+```
+oxidized$ extra/device2yaml.rb
+Missing a host to connect to...
+
+Usages:
+- device2yaml.rb [user@]host -i file [options]
+- device2yaml.rb [user@]host -c "command1
+  command2
+  command3" [options]
+
+-i and -c are mutualy exclusive, one must be specified
+
+[options]:
+    -c, --commands "command list"    specify the commands to be run
+    -i, --input file                 Specify an input file for commands to be run
+    -o, --output file                Specify an output YAML-file
+    -t, --timeout value              Specify the idle timeout beween commands (default: 5 seconds)
+    -e, --exec-mode                  Run ssh in exec mode (without tty)
+    -h, --help                       Print this help
+```
+
+- `[user@]host` specifies the user and host to connect to the device. The
+password will be prompted interactively by the script. If you do not specify a
+user, it will use the user executing the script.
+- The commands that will be run on the device must be defined in
+`deviceyaml.rb`. You can give the commands online with `-c` or read them from a
+file (one line per command) with `-i`. The commands should match exactly the
+ones of the model (no abbreviations) and include the commands of the
+`post_login` and `pre_logout` sections. When using `-c` and editing the shell
+command line, `CTRL-V CTRL-J` is very useful to add a line break.
+- `device2yaml.rb` waits an idle timeout after the last received data
+before sending the next command. The default is 5 seconds. If your device makes
+a longer pause than 5 seconds before or within a command, you will see that the
+output of the command is shortened or slips into the next command in the YAML
+file. You will have to change the idle timeout to a greater value to address
+this.
+- When run without the output argument, `device2yaml.rb` will only print the SSH
+output to the standard output. You must use `-o <model:HW_SW:simulation.yaml>`
+to store the collected data in a YAML file.
+- If your Oxidized model uses SSH exec mode (look for `exec true` in the model),
+you will have to use the option `-e` to run `device2yaml.rb` in SSH exec mode.
+
+Note that `device2yaml.rb` takes some time to run because of the idle timeout of
+(default) 5 seconds between each command. You can press the "Escape" key if you
+know there is no more data to come for the current command (when you see the
+prompt for the next command), and the script will stop waiting and directly
+process the next command.
+
+
+Running the script against an ios device would look like:
+```shell
+extra/device2yaml.rb oxidized@r61 -c "terminal length 0
+terminal width 0
+show version
+show vtp status
+show inventory
+show running-config
+exit" -o spec/model/data/ios:C8200L_16.12.1:simulation.yaml
+```
+### Publishing the YAML Simulation File to Oxidized
+Publishing the YAML simulation file of your device helps maintain Oxidized. This
+task may take some time, and we are very grateful that you take this time for
+the community!
+
+You should pay attention to removing or replacing anything you don't want to
+share with the rest of the world, for example:
+
+- Passwords
+- IP Addresses
+- Serial numbers
+
+You can also shorten the configuration if you want - we don't need 48 times the
+same configuration for each interface, but it doesn't hurt either.
+
+Take your time, this is an important task: after you have uploaded your file on
+GitHub, it may be impossible to remove it.
+You can use search/replace to make consistent and faster changes, for example
+change the hostname everywhere.
+
+The YAML simulation files are stored under
+[/spec/model/data/](/spec/model/data/), with the naming convention
+`<model>:<description>:simulation.yaml`, where `<model>` is the lowercase name
+of the Oxidized model and `<description>` is the name of the test case.
+`<description>` is generally formatted as `<hardware>_<software>` or
+`<hardware>_<software>_<information>`.
+
+Using a correct name for the file is important to ensure it is included in
+automatic model unit tests.
+
+Examples:
+
+- spec/model/data/aoscx:R0X25A-6410_FL.10.10.1100:simulation.yaml
+- spec/model/data/asa:5512_9.12-4-67_single-context:simulation.yaml
+- spec/model/data/ios:C9200L-24P-4G_17.09.04a:simulation.yaml
+
+When you are finished, commit and push to your forked repository on GitHub, and
+submit a Pull Request. Thank you for your help!
+
+### Interactive Mode
+The `device2yaml.rb` script is basic and sometimes needs some help, especially
+when dealing with a device that sends its output page by page and requires you
+to press space for the next page. `device2yaml.rb` does not know how to handle
+this.
+
+While `device2yaml.rb` is running, you can type anything on the keyboard, and it
+will be sent to the remote device. So you can press space or 'n' to get the next
+page.
+
+You can also use this to enter an enable password.
+
+If you press the "Esc" key, `device2yaml.rb` will not wait for the idle timeout
+and will process the next command right away.
+
+### YAML Format
+The YAML file has two sections:
+- init_prompt: describing the lines sent by the device before we can send a
+command. It usually includes MOTD banners and must include the first prompt.
+- commands: the commands the Oxidized model sends to the network device and
+their outputs.
+
+The outputs are multiline and use YAML block scalars (`|`), with the trailing \n
+removed (`-` after `|`). The outputs include the echo of the given command and
+the next prompt. Escape characters are coded in Ruby style (\n, \r...).
+
+Here is a shortened example of a YAML file:
+```yaml
+---
+init_prompt: |-
+  \e[4m\rLAB-R1234_Garderos#\e[m\x20
+commands:
+  show system version: |-
+    show system version
+    grs-gwuz-armel/003_005_068 (Garderos; 2021-04-30 16:19:35)
+    \e[4m\rLAB-R1234_Garderos#\e[m\x20
+# ...
+  exit: ""
+```
+
+

data/docs/Hooks.md

@@ -2,6 +2,15 @@
 
 You can define an arbitrary number of hooks that subscribe to different events. The hook system is modular and different kind of hook types can be enabled.
 
+1. [Events](#events)
+2. Hook types
+ * [exec](#hook-type-exec)
+ * [githubrepo](#hook-type-githubrepo)
+ * [awssns](#hook-type-awssns)
+ * [slackdiff](#hook-type-slackdiff)
+ * [ciscosparkdiff](#ciscosparkdiff)
+ * [xmppdiff](#hook-type-xmppdiff)
+
 ## Configuration
 
 Following configuration keys need to be defined for all hooks:
@@ -184,6 +193,31 @@ hooks:
     privatekey: /root/.ssh/id_rsa
 ```
 
+### Custom branch name
+Githubrepo will use the branch name used in the
+[git output](Outputs.md#output-git) as a remote branch name. When creating the
+git repository for the first time, Oxidized uses the default branch name
+configured in git with `git config --global init.defaultBranch <Name>`. The
+default is `master`.
+
+If you need to rename the branch name after Oxidized has created it, you may do
+it manually. Be aware that you may break things. Make backups and do not
+complain if something goes wrong!
+
+1. Stop oxidized (no one should access the git repository while doing the
+following steps)
+2. Make a backup of your oxidized data, especially the git repository
+3. Change directory to your oxidized git repository (as configured in oxidized
+configuration file)
+4. Inspect the current branches with `git branch -avv`
+5. Rename the default branch with `git branch -m <NewName>`
+6. Remove the reference to the old remote branch  with
+   `git branch -r -d origin/<OldName>`
+6. Inspect the change with `git branch -avv`
+7. Restart oxidized - you're done!
+
+Note that you will also have to clean your remote git repository.
+
 ## Hook type: awssns
 
 The `awssns` hook publishes messages to AWS SNS topics. This allows you to notify other systems of device configuration changes, for example a config orchestration pipeline. Multiple services can subscribe to the same AWS topic.
@@ -225,13 +259,15 @@ gem install slack-ruby-client
 
 ### slackdiff hook configuration example
 
+> Please note that the channel needs to be your Slack channel ID.
+
 ```yaml
 hooks:
   slack:
     type: slackdiff
     events: [post_store]
     token: SLACK_BOT_TOKEN
-    channel: "#network-changes"
+    channel: "CHANNEL_ID"
 ```
 
 The token parameter is a Slack API token that can be generated following [this tutorial](https://api.slack.com/tutorials/tracks/getting-a-token).  Until Slack stops supporting them, legacy tokens can also be used.
@@ -244,13 +280,11 @@ hooks:
     type: slackdiff
     events: [post_store]
     token: SLACK_BOT_TOKEN
-    channel: "#network-changes"
+    channel: "CHANNEL_ID"
     diff: false
     message: "%{node} %{group} %{model} updated https://git.intranet/network-changes/commit/%{commitref}"
 ```
 
-Note the channel name must be in quotes.
-
 A proxy can optionally be specified if needed to reach the Slack API endpoint.
 
 ```yaml
@@ -259,7 +293,7 @@ hooks:
     type: slackdiff
     events: [post_store]
     token: SLACK_BOT_TOKEN
-    channel: "#network-changes"
+    channel: "#CHANNEL_ID"
     proxy: http://myproxy:8080
 ```
 

data/docs/Issues.md

@@ -0,0 +1,97 @@
+# Writing good issues
+If you're experiencing a problem with Oxidized or need a new feature, you can
+[submit an issue on github](https://github.com/ytti/oxidized/issues). We have
+a great community where users help each other through the issue system.
+
+This guide provides tips on writing your issue to make it easier for the
+community and developers to understand and respond effectively.
+
+Why write good issues?
+- A clear and detailed issue improves the chances of getting your problem resolved.
+- By spending time to write a good issue, you save developers time, contributing
+  to Oxidized’s progress without writing a line of code.
+
+## Submit to the correct project
+Choose the appropriate GitHub project based on your issue:
+
+- For issues with the web frontend or REST API, go to
+  [oxidized-web](https://github.com/ytti/oxidized-web/).
+- For issues with oxidized-script, use
+  [oxidized-script](https://github.com/ytti/oxidized-script). (note: as of
+  November 2024, oxidized-script is not actively maintained).
+- For issues with third-party software relying on Oxidized, open an issue in
+  that specific project.
+- For issues with Oxidized itself, go to
+  [oxidized](https://github.com/ytti/oxidized).
+
+## Format your issue
+- Use [GitHub Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to format your issue.
+- Preview your text before submitting to ensure it renders correctly.
+- Avoid screenshots of text. Instead, use [code formating](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code) for any relevant code snippets.
+
+## Choose your title well
+Keep the title brief yet descriptive. Aim to summarize the main issue or request in a few words.
+
+## Provide detailled informations
+Include as many relevant details as possible. At a minimum, specify:
+
+- Oxidized version and operating system.
+- Relevant parts of your Oxidized configuration and a brief explanation of your setup.
+- Output of the error, if relevant.
+- For issues related to specific devices, consider creating a YAML Simulation file (instructions below).
+
+Also, provide clear steps to reproduce the issue, if applicable.
+
+## Making feature requests
+Feature requests are welcome, but please understand that unaddressed requests
+may be closed after some time. If you need a feature urgently, consider
+contributing code via a pull request (PR) or hiring a developer.
+
+## Sumbit a YAML Simulation File
+To help developers troubleshoot device-specific issues, you may be asked to submit a
+[YAML simulation file](/docs/DeviceSimulation.md#creating-a-yaml-file-with-device2yamlrb) for your device.
+
+Here's a brief overview how to do it, you can find more details in the link
+above.
+- Fork Oxidized on github
+- Install dependencies (git and Ruby's Net::SSH):
+```
+# Adapt when not using a debian-based distro
+sudo apt install git ruby-net-ssh
+```
+- Clone your forked Oxidized repository:
+```
+git clone git@github.com:<your github user>/oxidized.git
+```
+- run the `extra/device2yaml.rb` script (you’ll be provided with the command to
+run) from the repository root:
+
+```
+extra/device2yaml.rb oxidized@r61 -c "terminal length 0
+terminal width 0
+show version
+show vtp status
+show inventory
+show running-config
+exit" -o spec/model/data/ios:C8200L_16.12.1:simulation.yaml
+```
+
+- The script waits 5 seconds between commands, and outputs the response of the
+  device. You can press "ESC" if you see the prompt and want to pass to next
+  command without waiting for the timeout.
+- The result will be stored in `spec/model/data/`.
+- Replace any sensitive information with placeholder values in the output file.
+- Commit & push the file to github
+```
+git add spec/model/data/ios:C8200L_16.12.1:simulation.yaml
+git commit -m "Device simulation for C8200L"
+git push
+```
+- Create a pull request (PR) in GitHub, referencing the issue number (e.g.,
+  "YAML simulation file for issue #1234").
+
+
+
+
+
+