[Solr Wiki] Update of "Editing configuration files in the admin UI" by ErickErickson

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Solr Wiki" for change notification.

The "Editing configuration files in the admin UI" page has been changed by ErickErickson:
https://wiki.apache.org/solr/Editing%20configuration%20files%20in%20the%20admin%20UI

Comment:
Added page outlining the new edit-files-in-the-admin-ui capability.

New page:
= Editing configuration files in the admin UI =

New to Solr 4.7 is the ability to edit the various files in a core (or collection) via the admin UI. After you select a core in the admin UI, you should see a link to "TBD". Clicking on this link will allow you to traverse the files in the conf directory and sub-directories. Clicking on a file will open up an editable text box and you'll be able to edit the contents of the file. When you're done editing you can click the "save" button. Yes, it's that simple.

<<TableOfContents>>

This works in both stand-alone and SolrCloud mode.

But you're not quite done once you've saved the files.

== Reload your core or collection ==

You ''must'' reload your core (or collection) to have your changes take effect. Failing to do this will cause you to ask "why didn't my changes take effect?".

(TBD) There is a button on the edit screen to issue the reload command.

<!> Note: reloading a ''core'' only reloads that instance. Other shards/replicas, whatever will not have these changes. However, reloading a ''collection'' in SolrCloud mode will cause the saved changes to be loaded on all the replicas of the collection.

== Disabling ==

This capability is enabled by default. It can be disabled by defining the "admin/file" file handler. The stock example solrconfig.xml file has a commented-out section that shows how to do this, but here's what you need to do:

{{{
  <requestHandler name="/admin/file" class="solr.admin.ShowFileRequestHandler" >
    <lst name="invariants">
      <str name="hidden">synonyms.txt</str>
      <str name="hidden">anotherfile.txt</str>
      <str name="hidden">*</str>
    </lst>
  </requestHandler>
}}}

The glob pattern currently ''only'' supports a single asterisk. Patterns like *.xml are '''not''' supported at this point.

== File permissions ==

Depending on how your system is set up, the user that Solr is running as may or may not have permissions to write to the conf directory for one or more cores and/or ZooKeeper. It is your responsibility to insure that the user configured to run Solr has the correct permissions else this will fail.

== Messing up the files ==

You can get into a state where you can no longer edit the files via the admin UI, especially in non-SolrCloud mode. Say you leave off a close tag in schema.xml, then reload. The core will fail to load and you'll see errors in your Solr log indicating the error, things like "<field> tag not properly terminated". Unfortunately, ''the core must load to use this functionality''. If you get into that situation, you'll need to manually edit the files, either on disk or push the corrections to ZooKeeper to correct the error and reload.

There are some errors that will be reported in the Solr log on reload that are not fatal that can still be corrected via editing in the admin UI, just be aware that there are some problems in both classes.


== SolrCloud .vs. non-SolrCloud ==

These two modes behave a bit differently, you should be aware of the differences.

=== SolrCloud ===

When you save a file when running in SolrCloud mode, that change is pushed to ZooKeeper. Changes will be distributed to all the replicas for the cluster ''when they reload or restart''. So it's important to understand that when you edit config files:
 * You will be affecting all the replicas for that collection (upon reload/restart)
 * When you reload the ''collection'' (as opposed to the core), all of the changes will be loaded onto all your replicas and they will be restarted. Neither the replica you're working on directly, nor any other nodes will have the new information until they're reloaded (or restarted).

=== non-SolrCloud ===

For a single stand-alone node, reloading the core is sufficient to see all your changes take effect. If you have more than one node in your setup (master slave or shards), it's more complicated.
 * Master/slave, 1 shard.
  * In this case, if you have configured your replication to replicate the files you're changing ''and'' are editing on the master, the next replication will push the changes to the slaves.
  * Otherwise, you'll need to manually distribute the changes to all the nodes.
 * Multiple shards (master/slave or not). Personally, I wouldn't use this capability in this situation on my live cluster. I'd get my configurations right on a stand-alone, single-shard machine and then use whatever automated scripts (you are automating pushing configs to all the nodes, right?) to push the changes out once I was satisfied with them.


== Managed schemas ==

There's the new "managed schema" kid in town that's really cool, especially for wizards & etc. The ability we're talking about here is a sledgehammer in comparison; it just blasts the entire file up to the server.

The managed schema relies on being able to effectively write out an in-memory structure to the schema.xml. So if you try to mix the two, you'll probably be puzzled. Until mixing the two is formally supported, we recommend that you use one or the other and do ''not'' try to mix them as far as schema.xml is concerned.

It should be OK to use the managed schema alongside this all-file configuration editing as long as you don't edit the schema.xml file in the admin UI.