Add RSE configuration guide for operators

docs/operator/configuration_parameters.md

@@ -495,43 +495,52 @@ a setting already specified in the Configuration File.
   - ***VO***: _(Optional)_ Internal short VO name. No default.
 
 ## RSE settings
-The RSE settings are set separately using `rucio.RSEClient.update_rse` or `rucio rse update`, and specifies RSE configuration used by the Rucio instance.
+The RSE settings are set separately using `rucio.RSEClient.update_rse` or `rucio rse update`, and specify RSE configuration used by the Rucio instance.
 Mutable settings are `deterministic`, `rse_type`, `staging_area`, `volatile`, `qos_class`, `availability_delete`, `availability_read`, `availability_write`, `city`, `country_name`, `latitude`, `longitude`, `region_code`, and `time_zone`.
+Geographic fields (`city`, `country_name`, `latitude`, `longitude`, `region_code`, `time_zone`) can also be set at RSE creation time via API parameters.
 Read more about RSEs [here](started/concepts/rucio_storage_element.md)
 and how to set them up [here](operator/configuration.md#creating-new-rses).
 
 - **availability_delete**: Boolean. Control if this RSE allows deletions by the Reaper daemon using any protocol. Default: `True`.
 - **availability_read**: Boolean. Control if this RSE allows reads using any protocol. Default: `True`.
 - **availability_write**: Boolean. Control if this RSE allows writes using any protocol. Default: `True`.
-- **credentials**: Dictionary[String, Any]: Specify token credentials used for accessing this RSE if it is in a commercial cloud. No default.
-- **delete_protocol**: Integer: Cannot be changed. Controls matching of protocol priorities for deletions. Default: `1`.
-- **deterministic**: Boolean: Controls if the RSE is allowed to generate paths based solely on the DID (scope:filename). More info about non-deterministic RSEs [here](started/concepts/replica_workflow.md#replica-paths-on-storage). Default: `True`.
-- **domain**: List[String]: Specifies the locations this RSE may be accessed by clients from. Cannot be changed.
-- **id**: String: Identification string of the RSE. Cannot be changed.
-- **lfn2pfn_algorithm**: String: Name of the algorithm in the configured policy package to be used for creating replica paths. Cannot be changed. If no lfn2pfn_algorithm attribute is set, then the setting defaults to lfn2pfn_algorithm_default in the configured policy package. Default: `default`.
-- **qos_class**: String: No functionality in modern Rucio. No default.
-- **read_protocol**: Integer: Cannot be changed. Controls matching of protocol priorities for reads. Default: `1`.
-- **rse**: String: The name of the Rucio Storage Element as given at creation time. Cannot be changed.
-- **rse_type**: String: Specify `DISK` or `TAPE` for control of [QoS](operator/qos_rse_config.md). Default: `DISK`.
-- **sign_url**: Optional[str]. Enable cloud support for this storage element. No default.
-- **staging_area**: Boolean.Specify if this RSE is a disk buffer to a tertiary storage backend, subject to additional constraints (specifically a lifetime for rules on this RSE must be defined). Default: `False`.
-- **third_party_copy_read_protocol**: Integer: Cannot be changed. Controls matching of protocol priorities for TPC reads. Default `1`.
-- **third_party_copy_write_protocol**: Integer: Cannot be changed. Controls matching of protocol priorities for TPC writes. Default `1`.
-- **verify_checksum**: Boolean: Specifies if the RSE has support for checksum verification. Default: `True`.
+- **city**: Optional[String]. City where the RSE is located. Used for geographic RSE selection. No default.
+- **continent**: Optional[String]. Continent where the RSE is located. No default.
+- **country_name**: Optional[String]. Country where the RSE is located. Used for geographic RSE selection. No default.
+- **credentials**: Optional[Dictionary[String, Any]]. Specify token credentials used for accessing this RSE if it is in a commercial cloud. No default.
+- **deterministic**: Boolean. Controls if the RSE is allowed to generate paths based solely on the DID (scope:filename). More info about non-deterministic RSEs [here](started/concepts/replica_workflow.md#replica-paths-on-storage). Default: `True`.
+- **domain**: List[String]. Specifies the locations this RSE may be accessed by clients from. Cannot be changed.
+- **id**: String. Identification string of the RSE. Cannot be changed.
+- **latitude**: Optional[Float]. Latitude coordinate of the RSE location. Used for geographic calculations. No default.
+- **longitude**: Optional[Float]. Longitude coordinate of the RSE location. Used for geographic calculations. No default.
+- **protocols**: List[RSEProtocolDict]. List of protocol configurations for accessing this RSE. Cannot be changed directly; use protocol-specific methods.
+- **qos_class**: Optional[String]. No functionality in modern Rucio. No default.
+- **region_code**: Optional[String]. Region code where the RSE is located (e.g., state or province). No default.
+- **rse**: String. The name of the Rucio Storage Element as given at creation time. Cannot be changed.
+- **rse_type**: String. Specify `DISK` or `TAPE` for control of [QoS](operator/qos_rse_config.md). Default: `DISK`.
+- **sign_url**: Optional[String]. Enable cloud support for this storage element. No default.
+- **staging_area**: Boolean. Specify if this RSE is a disk buffer to a tertiary storage backend, subject to additional constraints (specifically a lifetime for rules on this RSE must be defined). Default: `False`.
+- **time_zone**: Optional[String]. Time zone of the RSE location (e.g., "Europe/Zurich"). No default.
+- **verify_checksum**: Boolean. Specifies if the RSE has support for checksum verification. Default: `True`.
 - **volatile**: Boolean. Specifies if the RSE is cache storage. Subject to volatile RSE restrictions detailed [here](https://rucio.github.io/documentation/operator/qos_rse_config). Default: `False`.
-- **write_protocol**: Integer: Cannot be changed. Controls matching of protocol priorities for writes. Default: `1`.
+
+The following fields are compatibility fields that may be present in the settings dictionary:
+- **protocol**: RSEProtocolDict. A single protocol configuration (for backward compatibility).
+- **prefix**: String. Protocol-specific prefix path.
+- **scheme**: String. Protocol scheme (e.g., `https`, `gsiftp`).
+- **hostname**: String. Hostname of the storage endpoint.
 
 ## RSE attributes
-The RSE Attributes are set separately using `rucio.RSEClient.add_rse_attribute` or `rucio rse attribute add`.
-and only contains information about the specific RSE's for the Rucio instance.
+The RSE Attributes are set separately using `rucio.RSEClient.add_rse_attribute` or `rucio rse attribute add`,
+and only contain information about the specific RSEs for the Rucio instance.
 Read more about RSEs [here](started/concepts/rucio_storage_element.md)
 and how to set them up [here](operator/configuration.md#creating-new-rses).
 
 - **associated_sites**: String. Separated by commas. Used for chaining of subscriptions so that transfers to one RSE will also be mirrored to associated_sites. No default.
-- **archive_timeout**: Integer: Only used for transfers with a tape destination. Controls the number of seconds the FTS3 transfer manager will wait for the tape archival of the file to go `FAILED` or `FINISHED`. No default.
-- **auto_approve_bytes**: String: Upper limit for the size in bytes of a DID for which rules will be automatically approved. Example: `500GB`. No default.
-- **auto_approve_files**: Integer: Upper limit for the number of files covered by a rule which will be automatically approved. No default.
-- **available_for_multihop**:  Boolean. If True, allow to use this RSE as an intermediate hop in a multi-hop transfer. Default: `False`.
+- **archive_timeout**: Integer. Only used for transfers with a tape destination. Controls the number of seconds the FTS3 transfer manager will wait for the tape archival of the file to go `FAILED` or `FINISHED`. No default.
+- **auto_approve_bytes**: String. Upper limit for the size in bytes of a DID for which rules will be automatically approved. Example: `500GB`. No default.
+- **auto_approve_files**: Integer. Upper limit for the number of files covered by a rule which will be automatically approved. No default.
+- **available_for_multihop**: Boolean. If True, allow to use this RSE as an intermediate hop in a multi-hop transfer. Default: `False`.
 - **block_manual_approval**: Boolean. Disable manual rule approval for this RSE. Default: `False`.
 - **bittorrent_tracker_addr**: String. Used to configure the URL of the bittorrent tracker API when using the torrent transfer manager. No Default.
 - **checksum_key**: String. Used to specify an alternate RSE attribute to search for supported checksums beyond those with global support (ADLER32, MD5). Default: `supported_checksums`.
@@ -541,15 +550,15 @@ and how to set them up [here](operator/configuration.md#creating-new-rses).
 - **fts**: String. Specify the REST API URL of the FTS3 transfer manager. No default.
 - **greedyDeletion**: Boolean. Allow files without a rule locking them to be deleted by a Reaper Daemon. Default behavior only marks a file for deletion when there is no space on an RSE for a new required file. Default: `False`.
 - **group_by_rse_attribute**: String. Control the RSE attribute (such as `country`) which transfer source RSEs will be grouped by when determining an appropriate transfer source. Default: `UNKNOWN`.
+- **lfn2pfn_algorithm**: String. Name of the algorithm to be used for generating paths to files on **deterministic RSEs**. Must be defined in the configured policy package. If not set, defaults to `lfn2pfn_algorithm_default` from the `[policy]` section of the config file. Common values: `identity`, `hash`. Default: `default`. Note: This attribute is also included in the RSE settings dictionary when protocols are retrieved.
 - **globus_endpoint_id**: String. Specify the REST API URL of the Globus transfer manager. No default.
 - **hop_penalty**: Integer. Usage cost of this RSE as an intermediate in [multihop transfers](operator_transfers/transfers_overview.md). Overrides the global `transfers/hop_penalty` configuration for this particular RSE.
  Requires `available_for_multihop` attribute is True on the RSE. No default.
 - **is_object_store**: Boolean. Control the auditor daemon's behavior. Instead of dumping all files, list them by date. Default: `False`.
-- **istape**: Boolean. Default: `False`.
-- **lfn2pfn_algorithm**: String. Name of the algorithm to be used for generating paths to files on the storage. Must be defined in the configured policy package. Default: `default`.
+- **istape**: Boolean. Default: `False`. Historically used within RSE expressions. Not needed by Rucio itself. Refer to `rse_type` setting instead.
 - **mock**: Boolean. Default: `False`.
 - **multihop_tombstone_delay**: Integer. Delay before a multihop transfer intermediate rule is to be deleted. Defined in seconds. Default: `7200`.
-- **naming_convention**: String. Name of the algorithm in the configured policy package which is to be used to validate DIDs on this RSE. Default: `None`.
+- **naming_convention**: String. Name of the `non_deterministic_pfn` algorithm in the configured policy package used to generate physical filenames for **non-deterministic RSEs** (typically tape systems). Unlike `lfn2pfn_algorithm` (used for deterministic RSEs), this algorithm can use file metadata, dataset membership, and other contextual information to construct filenames. Only applies to replications (not direct uploads). Default: `None`.
 - **oidc_support**: Boolean. Specifies that the RSE supports OIDC authentication for FTS3 transfers. Default: `False`.
 - **overwrite_when_only_on_disk**: Boolean. On a `TAPE` RSE, controls if a file can be overwritten. A file may only be overwritten if it has not yet been written to the tape backend. Default: `False`.
 - **overwrite**: Boolean. Controls if a file can be overwritten on the RSE. Default: `True` for `rse_type: DISK`. `False` for `rse_type: TAPE`.