
[[file-editor]]
= File Editor
:description: Learn how to use the File Editor in OpenNMS {page-component-title} to view and edit configuration (.xml, .cfg, etc.) files through the UI.

The File Editor page lets you view and edit configuration files (`.xml`, `.cfg`, `.drl`, and so on) in the {page-component-title} UI instead of having to edit them in your local file system (for example, by locating the file in your `/etc` directory and editing it with a text editor).
To access the file editor, log in to the web UI and click menu:Tools[File Editor] in the side menu.

IMPORTANT: This menu item and page will *only* display when the current user has the `ROLE_FILESYSTEM_EDITOR`.
This is separate from the `ROLE_ADMIN` role.

NOTE: Changing the configuration files will affect the operation of {page-component-title}.
Incorrectly editing a file could result in features no longer working, or not working as intended.

== View files

By default, the File Editor page displays a tree view of your OpenNMS `/etc` directory.
From this page, you can do the following:

* Navigate to and open any file in your OpenNMS directory.
* Expand and collapse subtrees (subdirectories).
* Search for a directory name.
* Search for any part of a file.
* View and edit files.

.File Editor page with directory tree and an open configuration file
image::configuration/file-editor-main.png[File editor, 700]

== Edit files

To edit a file, open it on the File Editor page and type in the text box.
Click *Save* to save your changes and update the configuration file.

CAUTION: Changing configuration files on the File Editor page overwrites the file on your disk.
There is currently no versioning or support for backup files.
While the file editor does not have support for Git, you may want to xref:deployment:upgrade/git-diff.adoc[set up your config folder as a Git repository].

Click *Reset* to reload the file from your local disk into the editor.

NOTE: Reloading the file will display it as it was last saved to your disk, not necessarily the file from before you edited it.

=== Activate configuration changes

Depending on which file you edit, {page-component-title} may detect and apply the configuration changes automatically.
In other cases, you may need to reload a daemon or restart your instance.

The following documentation provides more information on configuration files:

* xref:operation:deep-dive/admin/configuration/daemon-config-files.adoc[].
* xref:reference:daemons/introduction.adoc#ga-daemons[Daemon reference] (overview of all daemons, related configuration files, and which daemons can be reloaded without restarting {page-component-title}).

== Add and delete files

To add a new file to your OpenNMS directory, navigate to a subdirectory and click *Add* (*+*).
Type a name for the file, enter text in the *Edit* box, and click *Save*.

Note that validation will run on the file when you attempt to save it, and may prevent it from being saved.
If an error occurs, a message at the bottom of the text editor provides more information on why validation failed.

.Add a new file
image::configuration/file-editor-add-new.png[300,300]

To delete a file from your directory, navigate to a subdirectory, find the file that you want to delete, and click the *minus* symbol (*-*) beside its name.
Click *Confirm* in the dialog that appears to confirm deletion.

CAUTION: Deleting a file is permanent.
The file is removed from your local disk and is unrecoverable.

== The console

A console box is displayed at the bottom of the *Edit* box.
It displays detailed information after your perform certain actions (for example, saving or deleting a file).
To clear the console of text, click *Clear*.
To hide the console box, click *Minimize*.
