{
    "componentChunkName": "component---src-templates-markdown-doc-tsx",
    "path": "/2025.1.3/installation/ssh_configuration",
    "result": {"data":{"mdx":{"id":"bf853517-eb58-5807-975f-5c2f52980dbd","frontmatter":{"title":"","images":null},"body":"var _excluded = [\"components\"];\nfunction _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }\nfunction _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }\nfunction _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }\n/* @jsxRuntime classic */\n/* @jsx mdx */\n\nvar _frontmatter = {};\nvar layoutProps = {\n  _frontmatter: _frontmatter\n};\nvar MDXLayout = \"wrapper\";\nreturn function MDXContent(_ref) {\n  var components = _ref.components,\n    props = _objectWithoutProperties(_ref, _excluded);\n  return mdx(MDXLayout, _extends({}, layoutProps, props, {\n    components: components,\n    mdxType: \"MDXLayout\"\n  }), mdx(\"h1\", null, \"SSH Configuration\"), mdx(\"p\", null, \"All communication in Salvus with remote sites (that is for all site types except\\n\", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"local\"), \") happens via \", mdx(\"a\", {\n    parentName: \"p\",\n    \"href\": \"https://en.wikipedia.org/wiki/Secure_Shell\"\n  }, \"SSH\"), \", thus a\\nproper SSH configuration is necessary. We explain some basics in this document,\\nwith a large amount of additional information available on the web.\"), mdx(\"p\", null, \"If this is the first time you are dealing with SSH the process may appear a bit\\ninvolved. Keep in mind that it only has to be done once and is in general useful\\nfor connecting to other remote machines.\"), mdx(\"p\", null, \"There are two files which you might have to edit with information gained from\\nthis document here:\"), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"Salvus' site config file which can be edited by calling\")), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-bash\"\n  }, \"salvus-cli edit-config\\n\")), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"The SSH config file usually located at \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"~/.ssh/config\"), \".\\nIf the file does not exist yet, we will create it.\")), mdx(\"h2\", null, \"Key-Based Authentication\"), mdx(\"p\", null, \"Instead of authenticating via username and password, Salvus only supports the\\nmuch safer key-based authentication method of SSH. In a nutshell, it works\\nby storing a cryptographic key pair in your home directory split into a\\n\", mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"public key\"), \" and a \", mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"private key\"), \".\\nAfter copying the public key to other machines, the private key is then used\\nto prove to the remote machine that you are who you claim you are.\\nThis is very safe and also more convenient as one no longer has to enter a\\npassword when connecting via SSH.\"), mdx(\"h3\", null, \"Creating a SSH Key Pair\"), mdx(\"p\", null, \"If you do not yet have a SSH key pair, create a new one with:\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-keygen -t rsa -b 4096 -C \\\"your_email@example.com\\\"\\n\")), mdx(\"p\", null, \"Make sure to enter a password. Otherwise security is degraded.\"), mdx(\"p\", null, \"In case you are unsure if you already have one, check the contents of the\\n\", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"~/.ssh\"), \" directory and watch out for \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"id_rsa\"), \" and \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"id_rsa.pub\"), \".\\nThose are the default names and location of the private and the public key,\\nrespectively.\"), mdx(\"p\", null, \"Once this is done add the key to the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" with\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-add [-K] [/path/to/key]\\n\")), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"/path/to/key\"), \" can be omitted for the default path, which is \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"~/.ssh/id_rsa\"), \".\\nThe \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" is described in more detail further down this page. The \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"-K\"), \" is\\nnecessary if you want to add/later retrieve the key to a FIDO authenticator\\nwhich you likely want to do.\"), mdx(\"p\", null, \"Make sure the key is part of the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" by calling\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-add -l\\n\")), mdx(\"p\", null, \"Finally copy the public key to the remote machine you want use Salvus on with\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-copy-id USERNAME@HOSTNAME\\n\")), mdx(\"p\", null, \"you will have to enter the password to the remote machine once, but\\nafterwards you should be able to log-in to the remote machine with\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh USERNAME@HOSTNAME\\n\")), mdx(\"p\", null, \"This might be all the set-up you require for using Salvus on the remote site.\\nThe rest of this document goes into more detail and explains a few\\nedge-cases.\"), mdx(\"h3\", null, \"Encrypted SSH Keys\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"We strongly recommend to only use encrypted SSH keys!\")), mdx(\"p\", null, \"When creating an SSH key pair you are asked for a passphrase. If you give one\\nit will be used to locally encrypt the SSH keys. This adds another layer of\\nsecurity as the password will be required to use the SSH key. This decreases\\nthe attack surface in the case of data theft.\"), mdx(\"p\", null, \"Salvus supports two ways of decrypting said SSH keys:\"), mdx(\"h4\", null, \"Decrypting SSH Keys using \", mdx(\"inlineCode\", {\n    parentName: \"h4\"\n  }, \"ssh-agent\")), mdx(\"p\", null, \"This is the recommended way. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" is a helper tool that ships with most\\noperating systems. Once a key-pair has been added, the agent can decrypt it for\\napplications requiring it. This means that it only has to be entered once. Using\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-add -K\\n\")), mdx(\"p\", null, \"should suffice in most cases to add the default key to the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \".\"), mdx(\"p\", null, \"Some operating systems require a bit more effort to get the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" started.\\nPlease search the internet for appropriate solutions. A simple way to check if\\nthe \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" is set-up correctly is trying to log-in to a remote machine\\nwithout having to enter a password.\"), mdx(\"p\", null, \"To prevent having to add the key to the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" in every new shell it can be\\nadded to system wide authenticators. We recommend \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"keychain\"), \" on both macOS and\\nLinux although both confusingly are different programs. Please see\\n\", mdx(\"a\", {\n    parentName: \"p\",\n    \"href\": \"https://apple.stackexchange.com/questions/48502/how-can-i-permanently-add-my-ssh-private-key-to-keychain-so-it-is-automatically\"\n  }, \"here\"), \"\\nand\\n\", mdx(\"a\", {\n    parentName: \"p\",\n    \"href\": \"https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent\"\n  }, \"here\"), \"\\nfor more information.\"), mdx(\"h4\", null, \"Decrypting SSH Keys using the \", mdx(\"inlineCode\", {\n    parentName: \"h4\"\n  }, \"keyring\"), \" library\"), mdx(\"p\", null, \"If the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"ssh-agent\"), \" solution is for some reason not feasible for you, Salvus\\nsupports decrypting it using the\\n\", mdx(\"a\", {\n    parentName: \"p\",\n    \"href\": \"https://github.com/jaraco/keyring\"\n  }, mdx(\"inlineCode\", {\n    parentName: \"a\"\n  }, \"keyring\")), \" library. It works by storing\\nyour SSH key passphrase in whatever safe storage option your operating system\\nprovides.\"), mdx(\"p\", null, \"Install it with:\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"pip install keyring\\n\\n# Optional if you later get a message that you might have to install\\n# alternative back-ends:\\npip install keyrings.alt\\n\")), mdx(\"p\", null, \"You now have to add the SSH passphrase to \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"keyring\"), \" by calling (replace\\n\", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"SERVICE_NAME\"), \" and \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"USER_NAME\"), \" by more suitable names):\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"keyring set SERVICE_NAME USER_NAME\\n\")), mdx(\"p\", null, \"Then check if you can retrieve the password with:\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"keyring get SERVICE_NAME USER_NAME\\n\")), mdx(\"p\", null, \"Once this works just add the previously chosen service and user name to the\\nusually commented \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"[ssh_passphrase]\"), \" section in the TOML config file, which\\nyou can access with\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"salvus-cli edit-config\\n\")), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-toml\"\n  }, \"[ssh_passphrase]\\n    service_name = \\\"SERVICE_NAME\\\"\\n    username = \\\"USER_NAME\\\"\\n\")), mdx(\"h2\", null, \"FAQ\"), mdx(\"h3\", null, \"How Can I Check My SSH Key Passphrase?\"), mdx(\"p\", null, \"Entering the following command on the shell will ask you for the passphrase\\nof your local SSH key and raise an error if it is wrong.\\nIn the case of an unencrypted key it will not ask for a password.\"), mdx(\"pre\", null, mdx(\"code\", {\n    parentName: \"pre\",\n    \"className\": \"language-shell\"\n  }, \"ssh-keygen -y\\n\")));\n}\n;\nMDXContent.isMDXComponent = true;"},"site":{"siteMetadata":{"salvusDocVersions":{"current":"2026.5.0"}}}},"pageContext":{"id":"bf853517-eb58-5807-975f-5c2f52980dbd"}},
    "staticQueryHashes": ["1756726491","1865182279","3419370438","3597190305","4112489441","519097329"]}