Differences
This shows you the differences between the selected revisions of the page.
| config 2006-06-30 | config 2023-10-27 (current) | ||
| Line 1: | Line 1: | ||
| ====== Configuration Storage ====== | ====== Configuration Storage ====== | ||
| - | By default WinSCP stored its configuration into Windows registry. Optionally it can store it into an INI file. To switch the storage see //[[ui_pref_storage#configuration_storage|Storage tab]]// of Preferences window. | + | WinSCP can store its configuration both to Windows registry and INI file. When installed, the configuration is stored by default into the registry. Portable versions use by default an INI file (if possible). To switch the storage see //[[ui_pref_storage#configuration_storage|Storage page]]// of Preferences window. |
| - | On startup WinSCP looks for INI file in the directory from which it was started. The INI file must have an ''.INI'' extension and the same name as WinSCP executable. If it finds the INI file it loads configuration from it. If it does not find any, it uses the registry (of current user). This allows you to easily carry WinSCP with your [[config#portable_configuration|configuration on removable media or USB drive]]. | + | Note that [[administration|configuration of restrictions and enforcements]] by administrator, is always stored in Windows registry. |
| - | + | ||
| - | You may also use INI file in different folder or with different name using [[commandline|/ini switch]]. | + | |
| ===== Removing Configuration ===== | ===== Removing Configuration ===== | ||
| You can [[ui_cleanup|clean up all configuration data]] stored on your machine. | You can [[ui_cleanup|clean up all configuration data]] stored on your machine. | ||
| - | ===== Transferring the Configuration ===== | + | ===== [[export]] Exporting/Backing up the Configuration ===== |
| - | If you use registry as configuration storage, you may export/import following registry key to export/import the settings. | + | To export/back up your configuration, go to //Tools > Export/Backup configuration// on [[ui_login|Login dialog]]. |
| + | |||
| + | In older versions of WinSCP, use //Export// button on [[ui_preferences|Preferences dialog]]. | ||
| + | |||
| + | ===== [[import]] Importing/Restoring Configuration ===== | ||
| + | To import/restore the configuration, go to //Tools > Import/Restore configuration// on [[ui_login|Login dialog]]. | ||
| + | |||
| + | See also //[[faq_transfer_config|How do I transfer my settings from a non-working computer?]]// | ||
| + | |||
| + | ===== [[transfer]] Transferring the Configuration ===== | ||
| + | To transfer your configuration to another computer/location, [[#export|export the configuration]] to an INI file and then [[#import|import]] the file on the another computer/location. | ||
| + | |||
| + | If you want to transfer just one specific stored site, you can [[ui_generateurl|generate a session URL]] from the site on the source location (make sure you include //Advanced settings// to the URL). Transfer the URL to the target location, [[ui_login#pasting|paste it to the Login dialog]] and [[ui_login#new_site|save it]]. | ||
| + | |||
| + | ===== Sharing the Configuration between Machines ===== | ||
| + | //See [[guide_config_cloud|*]]//. | ||
| + | |||
| + | ===== [[registry_key]] Registry Key ===== | ||
| + | If you use registry as configuration storage, the configuration is stored under the following key: | ||
| <code> | <code> | ||
| [HKEY_CURRENT_USER\Software\Martin Prikryl\WinSCP 2] | [HKEY_CURRENT_USER\Software\Martin Prikryl\WinSCP 2] | ||
| </code> | </code> | ||
| - | If you do not know how to work with registry, switch to INI file. | + | ===== [[ini]] INI File Location ===== |
| + | When loading configuration, WinSCP first looks for an INI file in the directory, where WinSCP executable is stored in. The INI file needs to have an ''.ini'' extension and the same name as the executable (i.e. ''WinSCP.ini''). If INI file in not found there, WinSCP looks to application data directory of your user profile, i.e. to ''C:\Users\username\AppData\Roaming\WinSCP.ini''. &winpath | ||
| - | If you use INI file as configuration storage, copy the ''winscp3.ini'' file from WinSCP installation directory on your source computer to installation directory on destination computer. The file is typically in following directory: | + | When you opt to use INI file for the first time, WinSCP tries to write it to directory, where WinSCP executable is stored in. If the directory is not writable, INI file is stored to application data directory of your user profile. |
| - | <code> | + | |
| - | c:\program files\winscp3\winscp3.ini | + | |
| - | </code> | + | |
| - | This file is automatically created when you switch to INI file configuration. | + | You may also use an INI file in a different folder or with a different name using ''[[commandline#configuration|/ini]]'' switch or in [[ui_pref_storage|preferences]]. |
| - | ===== Portable Configuration ===== | + | ===== [[no]] No Configuration ===== |
| - | You can configure WinSCP to be completely portable, i.e. make it store all its files and configuration in one place, portable drive (such as USB drive). | + | |
| - | First, you need to turn to [[config#|INI file configuration]]. In addition to configuration, WinSCP stores by default some files to local drives: | + | With [[commandline#configuration|''/ini=nul'' command-line switch]], WinSCP starts with the default configuration and does not save the configuration on exit. That is particularly useful for [[scripting]], to make sure that the [[scripting#configuration|script always starts with all defaults]]. This is also the configuration mode used by [[library|WinSCP .NET assembly]]. |
| - | * Random seed file (file ''winscp.rnd'' in yours //Documents and Settings// folder) | + | |
| - | * [[temp_folders|Temporary files]] (system temporary folder) | + | |
| - | You can force WinSCP to store the files into different location in [[ui_pref_storage|preferences]]. You can use paths relative to WinSCP start folder. | + | ===== [[readonly]] Read-Only Configuration ===== |
| - | To change the storage directly in an INI file to the same location, where WinSCP is started from, set following parameters: | + | Particularly, when using a shared INI file or when pre-configuring WinSCP for a specific task, you may want to set the configuration or its parts read-only. |
| + | |||
| + | ==== [[readonly_sections]] Read-Only Configuration Sections ==== | ||
| + | |||
| + | You can set individual configuration sections read-only. This way you can for example prevent a user from changing default transfer settings, while still allowing other kinds of customizations. | ||
| + | |||
| + | Setting a configuration section read-only makes WinSCP silently discard any changes to that section, when saving the configuration. | ||
| + | |||
| + | An access to individual sections is controlled using an optional ''Access'' key. If the key is not set, a section inherits the state of its parent section. By default, all sections are writable. To set a section read-only, set its ''Access'' key to ''readonly''. To enable writing to a subsection of a read-only section, set the subsection ''Access'' key to ''full''. | ||
| + | |||
| + | To change the default state of whole configuration, set root ''Access'' key. In Windows registry, it is a key in [[config#registry_key|WinSCP root registry key]]. As INI files have no root section, WinSCP looks into a special section named ''[_]'' (a single underscore). | ||
| + | |||
| + | For example the following INI file sets all configuration read-only, with an exception of a host key cache and interface settings (but in turn with an exception of transfer settings, which are again read-only): | ||
| <code ini> | <code ini> | ||
| + | [_] | ||
| + | Access=read | ||
| + | |||
| + | [SshHostKeys] | ||
| + | Access=full | ||
| + | ... | ||
| + | |||
| [Configuration\Interface] | [Configuration\Interface] | ||
| - | RandomSeedFile=.\winscp.rnd | + | Access=full |
| - | DDTemporaryDirectory=.\ | + | ... |
| + | |||
| + | [Configuration\Interface\CopyParam] | ||
| + | Access=read | ||
| + | ... | ||
| </code> | </code> | ||
| + | |||
| + | ==== [[ini_readonly]] Read-Only INI File ==== | ||
| + | A simpler way to make whole configuration read-only is to use an INI file and set it read-only in a file system. | ||
| + | |||
| + | When INI file directory or the file itself is not writable (for example when the INI file is in ''Program Files'' folder or when it is explicitly set read-only), WinSCP does not preserve its state when exiting. No error message is displayed. Only when you explicitly change configuration (such as when you save [[session_configuration|site]], or submit [[ui_preferences|Preferences dialog]]), an error is shown. You can make WinSCP overwrite a read-only INI file by holding ''Shift'' key, while closing or submitting Preferences dialog. | ||
| + | |||
| + | ===== [[auto]] Auto-selecting Storage ===== | ||
| + | On startup, WinSCP first looks for an [[config#ini|INI file]] in the directory, where WinSCP executable is stored in;((Unless different location was forced using [[commandline#configuration|''/ini'' switch]].)) and then in the user profile directory. If it does not find INI file in either location, it looks for presence of [[config#registry_key|its key in registry]], both in ''HKCU'' and ''HKLM''. The ''HKLM'' key is created by the [[installation|installer]], so installed WinSCP uses the registry by default. If it does not find the registry key either, it creates an empty INI file in the directory, where WinSCP executable is stored in. If that directory is not writable, it creates an empty INI file in the user profile directory. | ||
| + | |||
| + | ===== Checking What Store Is in Use ===== | ||
| + | When [[troubleshooting]] problems, it is necessary to find whether WinSCP is actually using the configuration storage you intended. For that inspect a beginning of the [[logging|session log]]: | ||
| + | |||
| + | <code> | ||
| + | -------------------------------------------------------------------------- | ||
| + | WinSCP Version 5.15.3 (Build 9730) (OS 10.0.18362 - Windows 10 Enterprise) | ||
| + | Configuration: HKCU\Software\Martin Prikryl\WinSCP 2\ | ||
| + | Log level: Normal | ||
| + | Local account: INTRANET\martin | ||
| + | </code> | ||
| + | |||
| + | Tag ''Configuration'' shows either ''HKCU'' Windows registry key or a path to an INI file. When Windows registry configuration storage is in use, it is also important under what Windows account is WinSCP running, to know what account the ''HKCU'' refers to. For that refer to ''Local account'' tag. | ||
| + | |||
| + | ===== Portable Configuration ===== | ||
| + | Learn how to configure WinSCP for [[portable|portable use]]. | ||
| ===== Pre-configuring WinSCP ===== | ===== Pre-configuring WinSCP ===== | ||
| Learn how to [[custom_distribution|distribute pre-configured version of WinSCP]]. | Learn how to [[custom_distribution|distribute pre-configured version of WinSCP]]. | ||
| - | |||