diff --git a/docs/.gitbook/assets/CleanShot 2024-12-16 at 14.24.10@2x.png b/docs/.gitbook/assets/CleanShot 2024-12-16 at 14.24.10@2x.png new file mode 100644 index 000000000..1cf86212d Binary files /dev/null and b/docs/.gitbook/assets/CleanShot 2024-12-16 at 14.24.10@2x.png differ diff --git a/docs/.gitbook/assets/NoPorts Policy Diagrams.png b/docs/.gitbook/assets/NoPorts Policy Diagrams.png new file mode 100644 index 000000000..de931b855 Binary files /dev/null and b/docs/.gitbook/assets/NoPorts Policy Diagrams.png differ diff --git a/docs/.gitbook/assets/NoPorts-Connection-Diagram.png b/docs/.gitbook/assets/NoPorts-Connection-Diagram.png new file mode 100644 index 000000000..b73685f44 Binary files /dev/null and b/docs/.gitbook/assets/NoPorts-Connection-Diagram.png differ diff --git a/docs/.gitbook/assets/atPlatform Diagram.png b/docs/.gitbook/assets/atPlatform Diagram.png new file mode 100644 index 000000000..15c904791 Binary files /dev/null and b/docs/.gitbook/assets/atPlatform Diagram.png differ diff --git a/docs/.gitbook/includes/activate-cli-client-unix.md b/docs/.gitbook/includes/activate-cli-client-unix.md new file mode 100644 index 000000000..816cedb75 --- /dev/null +++ b/docs/.gitbook/includes/activate-cli-client-unix.md @@ -0,0 +1,19 @@ +--- +title: activate-cli-client-unix +--- + +{% hint style="warning" %} +If you've activated your **client** atSign on another device already, this step will not work. Instead, follow this guide: [reuse-your-client-atsign-on-another-machine.md](../../installation-faq/reuse-your-client-atsign-on-another-machine.md "mention") +{% endhint %} + +This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign. + +``` +~/.local/bin/at_activate -a @_client +``` + +### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders + +at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number.\ +\ +Once activated, the master keys will save at `~/.atsign/keys`. diff --git a/docs/.gitbook/includes/activate-cli-device-unix.md b/docs/.gitbook/includes/activate-cli-device-unix.md new file mode 100644 index 000000000..87599b29e --- /dev/null +++ b/docs/.gitbook/includes/activate-cli-device-unix.md @@ -0,0 +1,15 @@ +--- +title: activate-cli-device-unix +--- + +This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign. + +``` +~/.local/bin/at_activate -a @_device +``` + +### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders + +at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number. + +Once activated, the management keys will be saved in `~/.atsign/keys`. diff --git a/docs/.gitbook/includes/apkam-1-unix.md b/docs/.gitbook/includes/apkam-1-unix.md new file mode 100644 index 000000000..cfff6652d --- /dev/null +++ b/docs/.gitbook/includes/apkam-1-unix.md @@ -0,0 +1,9 @@ +--- +title: apkam-1-unix +--- + +Run the following command. It should output a 6-character passcode. + +```bash +~/.local/bin/at_activate otp -a @_device +``` diff --git a/docs/.gitbook/includes/apkam-2-unix.md b/docs/.gitbook/includes/apkam-2-unix.md new file mode 100644 index 000000000..2ef872c4c --- /dev/null +++ b/docs/.gitbook/includes/apkam-2-unix.md @@ -0,0 +1,19 @@ +--- +title: apkam-2-unix +--- + +
~/.local/bin/at_activate enroll -a @<REPLACE>_device \
+  -s <PASSCODE> \
+  -p noports \
+  -k ~/.atsign/keys/@<REPLACE>_device_key.atKeys \
+  -d <DEVICE_NAME> \
+  -n "sshnp:rw,sshrvd:rw"
+
+ +### Once you see this text, you're ready to continue to the next step. + +``` +Submitting enrollment request +Enrollment ID: --------------------- +Waiting for approval; will check every 10 seconds +``` diff --git a/docs/.gitbook/includes/apkam-3-unix.md b/docs/.gitbook/includes/apkam-3-unix.md new file mode 100644 index 000000000..e1967f63e --- /dev/null +++ b/docs/.gitbook/includes/apkam-3-unix.md @@ -0,0 +1,11 @@ +--- +title: apkam-3-unix +--- + +Run the following command + +```bash +~/.local/bin/at_activate approve -a @_device \ + --arx noports \ + --drx +``` diff --git a/docs/.gitbook/includes/client-installation-complete.md b/docs/.gitbook/includes/client-installation-complete.md new file mode 100644 index 000000000..7931714d3 --- /dev/null +++ b/docs/.gitbook/includes/client-installation-complete.md @@ -0,0 +1,7 @@ +--- +title: client-installation complete +--- + +{% hint style="success" %} +Your client machine software installation is completed. Now, on to the device/server! +{% endhint %} diff --git a/docs/.gitbook/includes/dart-binary-releases-table.md b/docs/.gitbook/includes/dart-binary-releases-table.md new file mode 100644 index 000000000..4e5176928 --- /dev/null +++ b/docs/.gitbook/includes/dart-binary-releases-table.md @@ -0,0 +1,10 @@ +--- +title: Dart Binary Releases Table +--- + +| Platform | Linux | macOS | Windows | +| -------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| x64 | [sshnp-linux-x64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-x64.tgz) | [sshnp-macos-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-x64.zip) (intel) | [sshnp-windows-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-windows-x64.zip) | +| arm64 | [sshnp-linux-arm64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm64.tgz) | [sshnp-macos-arm64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-arm64.zip) (apple) | | +| arm | [sshnp-linux-arm.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm.tgz) | | | +| risc-v | [sshnp-linux-riscv.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-riscv.tgz) | | | diff --git a/docs/.gitbook/includes/desktop-app-release-table.md b/docs/.gitbook/includes/desktop-app-release-table.md new file mode 100644 index 000000000..1295c3bdc --- /dev/null +++ b/docs/.gitbook/includes/desktop-app-release-table.md @@ -0,0 +1,5 @@ +--- +title: Desktop App Release Table +--- + +
Operating SystemDownload Location
WindowsWindows Store
MacOSApp Store
LinuxBuild from Source
diff --git a/docs/.gitbook/includes/device-activate-preamble.md b/docs/.gitbook/includes/device-activate-preamble.md new file mode 100644 index 000000000..90436cd44 --- /dev/null +++ b/docs/.gitbook/includes/device-activate-preamble.md @@ -0,0 +1,9 @@ +--- +title: device-activate-preamble +--- + +{% hint style="info" %} +Even though this atSign is for the device, we recommend activating it from your client. + +More info: [why-activate-the-device-atsign-on-the-client.md](../../installation-faq/why-activate-the-device-atsign-on-the-client.md "mention") +{% endhint %} diff --git a/docs/.gitbook/includes/device-warning-setup-client-first.md b/docs/.gitbook/includes/device-warning-setup-client-first.md new file mode 100644 index 000000000..93b8218f8 --- /dev/null +++ b/docs/.gitbook/includes/device-warning-setup-client-first.md @@ -0,0 +1,7 @@ +--- +title: device-warning setup client first +--- + +{% hint style="danger" %} +If you don't already have a NoPorts client setup, start there before setting up the device. +{% endhint %} diff --git a/docs/.gitbook/includes/full-install-overview.md b/docs/.gitbook/includes/full-install-overview.md new file mode 100644 index 000000000..e0a6b35ec --- /dev/null +++ b/docs/.gitbook/includes/full-install-overview.md @@ -0,0 +1,32 @@ +--- +title: full-install-overview +--- + +# Overview of the Process + +Before you begin, you may want an overview of the guide. + +
+ +<- Click the arrow to open the overview + +**Step 1**: Client machine setup + +* This process will involve installing the client and activation software on the client machine (1.1 & 1.2) +* Then we will activate the management keys on your client machine (1.3 & 1.4) + * The management keys allow you to administer more keys for other devices and should be kept in a safe place + +**Step 2**: Device setup + +* This process looks similar to step one, but will be done on the device +* This step will install the device and activation installer on the device (2.1 & 2.2) + +**Step 3**: Activating the device + +* Since we created the management keys on the client, we will now authorize a set of keys for the device. +* These new keys for the device will be cut on the device and have limited access to improve your device's security +* First we will generate an authorized pass code from the client (3.1) +* We will use that passcode to generate an authorization request on the device (3.2) +* Then we will approve the authorization request from the device (3.3) + +
diff --git a/docs/.gitbook/includes/get-atsigns-from-reg-warning.md b/docs/.gitbook/includes/get-atsigns-from-reg-warning.md new file mode 100644 index 000000000..c8cf4a2c0 --- /dev/null +++ b/docs/.gitbook/includes/get-atsigns-from-reg-warning.md @@ -0,0 +1,7 @@ +--- +title: get-atsigns-from-reg-warning +--- + +{% hint style="danger" %} +If you don't own a pair of atSigns/addresses, please visit [the registrar](https://my.noports.com/no-ports-invite/14dayfreetrial) before continuing +{% endhint %} diff --git a/docs/.gitbook/includes/installation-complete-visit-usage.md b/docs/.gitbook/includes/installation-complete-visit-usage.md new file mode 100644 index 000000000..face10557 --- /dev/null +++ b/docs/.gitbook/includes/installation-complete-visit-usage.md @@ -0,0 +1,9 @@ +--- +title: Installation Complete - visit usage +--- + +{% hint style="success" %} +Installation Complete!\ +\ +You are ready to use No Ports, visit [usage](../../usage/ "mention")! +{% endhint %} diff --git a/docs/.gitbook/includes/installation-legend.md b/docs/.gitbook/includes/installation-legend.md new file mode 100644 index 000000000..553f8000a --- /dev/null +++ b/docs/.gitbook/includes/installation-legend.md @@ -0,0 +1,9 @@ +--- +title: Installation legend +--- + +| Legend | Meaning | +| ---------- | ------------------------- | +| :desktop: | Client side | +| :printer: | Device side | +| \ | Fill in with your details | diff --git a/docs/.gitbook/includes/linux-macos-release-table.md b/docs/.gitbook/includes/linux-macos-release-table.md new file mode 100644 index 000000000..9a5742c0c --- /dev/null +++ b/docs/.gitbook/includes/linux-macos-release-table.md @@ -0,0 +1,10 @@ +--- +title: Linux/MacOS release table +--- + +| Platform | Linux | macOS | +| -------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| x64 | [sshnp-linux-x64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-x64.tgz) | [sshnp-macos-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-x64.zip) (intel) | +| arm64 | [sshnp-linux-arm64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm64.tgz) | [sshnp-macos-arm64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-arm64.zip) (apple) | +| arm | [sshnp-linux-arm.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm.tgz) | | +| risc-v | [sshnp-linux-riscv.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-riscv.tgz) | | diff --git a/docs/.gitbook/includes/mac-linux-full-install-video.md b/docs/.gitbook/includes/mac-linux-full-install-video.md new file mode 100644 index 000000000..1d9b48795 --- /dev/null +++ b/docs/.gitbook/includes/mac-linux-full-install-video.md @@ -0,0 +1,5 @@ +--- +title: Mac/Linux full install video +--- + +{% embed url="https://player.vimeo.com/video/1004237823?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0" %} diff --git a/docs/.gitbook/includes/universal.sh-download-command.md b/docs/.gitbook/includes/universal.sh-download-command.md new file mode 100644 index 000000000..28e2b8248 --- /dev/null +++ b/docs/.gitbook/includes/universal.sh-download-command.md @@ -0,0 +1,13 @@ +--- +title: universal.sh download command +--- + +```bash +curl -L https://github.com/atsign-foundation/noports/releases/latest/download/universal.sh -o universal.sh +``` + +To check if the installation downloaded correctly: + +```bash +ls | grep -w "universal.sh" +``` diff --git a/docs/.gitbook/includes/universal.sh-execute-activate-only.md b/docs/.gitbook/includes/universal.sh-execute-activate-only.md new file mode 100644 index 000000000..85d2574c4 --- /dev/null +++ b/docs/.gitbook/includes/universal.sh-execute-activate-only.md @@ -0,0 +1,5 @@ +--- +title: universal.sh execute - activate only +--- + +Type in `client` when asked for what type of install. You can either complete the install to have full client support, or press `ctrl + c` when it asks for more information to skip the rest of the client installation. diff --git a/docs/.gitbook/includes/universal.sh-execute-device-detail.md b/docs/.gitbook/includes/universal.sh-execute-device-detail.md new file mode 100644 index 000000000..8293a98c4 --- /dev/null +++ b/docs/.gitbook/includes/universal.sh-execute-device-detail.md @@ -0,0 +1,7 @@ +--- +title: universal.sh execute - device detail +--- + +The script will guide you through the installation process. It will prompt you for the information you need. Make sure you type in `device` when it asks what type of installation.\ +\ +**You will need the client atSign, device atSign and the device name. making sure they match your earlier choices.** diff --git a/docs/.gitbook/includes/universal.sh-execute.md b/docs/.gitbook/includes/universal.sh-execute.md new file mode 100644 index 000000000..2d2ac585b --- /dev/null +++ b/docs/.gitbook/includes/universal.sh-execute.md @@ -0,0 +1,10 @@ +--- +title: universal.sh execute +--- + +Make the script executable and run the script. + +```bash +chmod u+x universal.sh +./universal.sh +``` diff --git a/docs/.gitbook/includes/universal.sh-preamble.md b/docs/.gitbook/includes/universal.sh-preamble.md new file mode 100644 index 000000000..b60367aa1 --- /dev/null +++ b/docs/.gitbook/includes/universal.sh-preamble.md @@ -0,0 +1,7 @@ +--- +title: universal.sh preamble +--- + +First, make sure that you have [curl](https://curl.se) available on your system, curl is a common shell utility. + +The following command will download the `universal.sh` bash installer into your current directory: diff --git a/docs/.gitbook/includes/unversal.sh-execute-client-details.md b/docs/.gitbook/includes/unversal.sh-execute-client-details.md new file mode 100644 index 000000000..7c9551c6b --- /dev/null +++ b/docs/.gitbook/includes/unversal.sh-execute-client-details.md @@ -0,0 +1,13 @@ +--- +title: unversal.sh execute - client details +--- + +Type in **`client`** when asked for what type of install. Continue following along with the instructions provided with the installer until the installation is complete. + +### Useful tips when answering the client installation + +Your client atSign should look like : `@sshnp_client` + +Your device atSign should look like: `@sshnp_device` + +[Device name](../../installation-faq/installation-details.md#device-names) should look like: `my_host, pi3, home_server_2` diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index a6fd8f0f0..f260b88c6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,10 +2,19 @@ * [Home](README.md) * [Installation](installation/README.md) - * [Linux & MacOS Installation Guide](installation/linux/README.md) - * [Activating your atSigns](installation/linux/activating-your-atsigns.md) - * [Installation Details](installation/linux/installation-details.md) - * [Windows Installation Guide](installation/windows.md) + * [Quick Start for MacOS and Windows](installation/quick-start-for-macos-and-windows.md) + * [MacOS Installation Guides](installation/macos/README.md) + * [MacOS Desktop Client Installation](installation/macos/desktop.md) + * [MacOS CLI Client Installation](installation/macos/cli-client.md) + * [MacOS Device Installation](installation/macos/device.md) + * [Linux Installation Guide](installation/linux/README.md) + * [Linux Full Installation](installation/linux/full.md) + * [Linux Cli Client Installation](installation/linux/cli-client.md) + * [Linux Device Installation](installation/linux/device.md) + * [Windows Installation Guide](installation/windows/README.md) + * [Windows Desktop Client Installation](installation/windows/desktop.md) + * [Windows CLI Client Installation](installation/windows/cli-client.md) + * [Windows Device Installation](installation/windows/device.md) * [Manual Installation Guides](installation/advanced-installation-guides/README.md) * [Device installation](installation/advanced-installation-guides/device-installation-sshnpd/README.md) * [Tmux session](installation/advanced-installation-guides/device-installation-sshnpd/tmux-session.md) @@ -23,6 +32,14 @@ * [Automated Installation on Google Cloud Platform (GCP)](installation/cloud-installation-guides/automated-installation-on-google-cloud-platform-gcp.md) * [Automated Installation on Microsoft Azure](installation/cloud-installation-guides/automated-installation-on-microsoft-azure.md) * [Automated Installation on Oracle Cloud Infrastructure (OCI)](installation/cloud-installation-guides/automated-installation-on-oracle-cloud-infrastructure-oci.md) + * [Available Releases](installation/available-releases.md) + * [Desktop App Installation (MacOS & Windows)](installation/desktop-app-installation-macos-and-windows.md) +* [Installation FAQ](installation-faq/README.md) + * [How to activate an atSign](installation-faq/activating-your-atsigns.md) + * [Reuse your client atSign on another machine](installation-faq/reuse-your-client-atsign-on-another-machine.md) + * [How to name a device](installation-faq/installation-details.md) + * [How to generate SSH keys](installation-faq/how-to-generate-ssh-keys.md) + * [Why activate the device atSign on the client?](installation-faq/why-activate-the-device-atsign-on-the-client.md) * [Usage](usage/README.md) * [npt Usage](usage/basic-usage/README.md) * [Additional Configuration](usage/basic-usage/additional-configuration.md) @@ -30,7 +47,6 @@ * [Client Additional Configuration](usage/basic-usage-1/additional-configuration.md) * [sshnpd configuration](usage/sshnpd-configuration/README.md) * [Daemon Additional Configuration](usage/sshnpd-configuration/daemon-additional-configuration.md) - * [Quick SSH picker script](usage/quick-ssh-picker-script.md) * [Integrate with ssh config](usage/integrate-with-ssh-config.md) ## Use Cases @@ -44,7 +60,7 @@ ## Product Information -* [Managing Policies](reference/policy.md) +* [NoPorts Policy Service](reference/policy.md) * [FAQ](reference/faq.md) * [How It Works](reference/how-it-works.md) * [Under The Hood](reference/underthehood.md) diff --git a/docs/installation-faq/README.md b/docs/installation-faq/README.md new file mode 100644 index 000000000..eaf12bcb5 --- /dev/null +++ b/docs/installation-faq/README.md @@ -0,0 +1,24 @@ +# Installation FAQ + +Here are some helpful guides which may aid you if you get stuck during the installation process + +{% content-ref url="activating-your-atsigns.md" %} +[activating-your-atsigns.md](activating-your-atsigns.md) +{% endcontent-ref %} + +{% content-ref url="reuse-your-client-atsign-on-another-machine.md" %} +[reuse-your-client-atsign-on-another-machine.md](reuse-your-client-atsign-on-another-machine.md) +{% endcontent-ref %} + +{% content-ref url="installation-details.md" %} +[installation-details.md](installation-details.md) +{% endcontent-ref %} + +{% content-ref url="how-to-generate-ssh-keys.md" %} +[how-to-generate-ssh-keys.md](how-to-generate-ssh-keys.md) +{% endcontent-ref %} + +{% content-ref url="why-activate-the-device-atsign-on-the-client.md" %} +[why-activate-the-device-atsign-on-the-client.md](why-activate-the-device-atsign-on-the-client.md) +{% endcontent-ref %} + diff --git a/docs/installation/linux/activating-your-atsigns.md b/docs/installation-faq/activating-your-atsigns.md similarity index 70% rename from docs/installation/linux/activating-your-atsigns.md rename to docs/installation-faq/activating-your-atsigns.md index 402853131..f53f01661 100644 --- a/docs/installation/linux/activating-your-atsigns.md +++ b/docs/installation-faq/activating-your-atsigns.md @@ -2,17 +2,17 @@ icon: at --- -# Activating your atSigns +# How to activate an atSign ## Overview -SSH No Ports software needs to be installed on both the machine you are going to SSH to (device) and the machine you are going to SSH from (client). SSH No Ports uses [atSigns](https://atsign.com/faqs/) as addresses and you will need two, one for the client and one for the device +NoPorts software needs to be installed on both the machine you are going to connect to (device) and the machine you are going to connect from (client). NoPorts uses [atSigns](https://atsign.com/faqs/) as addresses and you will need two, one for the client and one for the device {% hint style="danger" %} If you don't own a pair of atSigns/addresses, please visit [the registrar](https://my.noports.com/no-ports-invite/14dayfreetrial) before continuing. {% endhint %} -Example client atSign +Example client atSign ``` @sshnp_client @@ -36,52 +36,32 @@ You will activate both the client atSign _**and**_ the device atSign on your cli (1) Run the at\_activate command for the client atSign -{% tabs %} -{% tab title="Linux" %} 
~/.local/bin/at_activate -a @<REPLACE>_client
-{% endtab %} - -{% tab title="macOS" %} -```bash -~/.local/bin/at_activate -a @_client -``` -{% endtab %} -{% endtabs %} (2) Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders at\_activate will pause and wait for the input of a one time pin (OTP) before you can continue. You should receive this pin to the contact information associated with the registration of your noports address (i.e. email or text message). {% hint style="warning" %} -If you are using a gmail.com account we have seen that sometimes the OTP gets stuck in the SPAM or PROMOTIONS folder. If you do not see the OTP check those folders. +If you are using a gmail.com account we have seen that sometimes the OTP gets stuck in the SPAM or PROMOTIONS folder. If you do not see the OTP check those folders. {% endhint %} -Once you receive the message, enter the pin into the application and press enter to continue. The application should proceed to create the cryptographic keys and store them in the `~/.atsign/keys/` directory with a filename that includes the atSign. +Once you receive the message, enter the pin into the application and press enter to continue. The application should proceed to create the cryptographic keys and store them in the `~/.atsign/keys/` directory with a filename that includes the atSign. ### Activate the device atSign 1\) Run the at\_activate command for the device atSign -{% tabs %} -{% tab title="Linux" %} 
~/.local/bin/at_activate -a @<REPLACE>_device
-{% endtab %} - -{% tab title="macOS" %} -```bash -~/.local/bin/at_activate -a @_device -``` -{% endtab %} -{% endtabs %} 2\) Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders Again, at\_activate will pause and wait for the input of a one time pin (OTP) before you can continue. You should receive this pin to the contact information associated with the registration of your noports address (i.e. email or text message). {% hint style="warning" %} -If you are using a gmail.com account we have seen that sometimes the OTP gets stuck in the SPAM or PROMOTIONS folder. If you do not see the OTP check those folders. +If you are using a gmail.com account we have seen that sometimes the OTP gets stuck in the SPAM or PROMOTIONS folder. If you do not see the OTP check those folders. {% endhint %} -Once you receive the message, enter the pin into the application and press enter to continue. The application should proceed to create the cryptographic keys and store them in the `~/.atsign/keys/` directory with a filename that includes the atSign. +Once you receive the message, enter the pin into the application and press enter to continue. The application should proceed to create the cryptographic keys and store them in the `~/.atsign/keys/` directory with a filename that includes the atSign. diff --git a/docs/installation-faq/how-to-generate-ssh-keys.md b/docs/installation-faq/how-to-generate-ssh-keys.md new file mode 100644 index 000000000..1f83dbd9c --- /dev/null +++ b/docs/installation-faq/how-to-generate-ssh-keys.md @@ -0,0 +1,15 @@ +--- +icon: key +--- + +# How to generate SSH keys + +SSH uses keys to authenticate as well as having a fallback of using passwords, but using keys is easier and more secure than "mypassword!". If you already are a seasoned user of SSH then you might have keys already but if not then on the client machine you can create a key pair using ssh-keygen. + +Example ssh-keygen command to create SSH Key Pair + +``` +ssh-keygen -t ed25519 -a 100 -f ~/.ssh/id_ed25519 +``` + +## diff --git a/docs/installation-faq/installation-details.md b/docs/installation-faq/installation-details.md new file mode 100644 index 000000000..86ac37cd0 --- /dev/null +++ b/docs/installation-faq/installation-details.md @@ -0,0 +1,17 @@ +--- +icon: memo-circle-info +--- + +# How to name a device + +Each device atSign can be used for multiple devices and so each device needs a unique name. The device name is limited to alphanumeric [snake case](https://www.tuple.nl/knowledge-base/snake-case) (lowercase alphanumeric separated by \_ ) up to 36 characters. + +Example snake case device names + +``` +my_host +canary02 +oci_mail_0001 +dc_001_row_009_rack_0067_ru_014 +``` + diff --git a/docs/installation-faq/reuse-your-client-atsign-on-another-machine.md b/docs/installation-faq/reuse-your-client-atsign-on-another-machine.md new file mode 100644 index 000000000..cd75ada01 --- /dev/null +++ b/docs/installation-faq/reuse-your-client-atsign-on-another-machine.md @@ -0,0 +1,48 @@ +--- +icon: file-import +--- + +# Reuse your client atSign on another machine + +## Want to use your atSign on a different machine? + +You can either: + +1. Generate a new set of cryptographic keys (Recommended), or +2. Copy the cryptographic keys from the machine where it's been activated in the past (Not recommended) + +### **1) Generate a new set of cryptographic keys (Recommended)** + +* We will use the same approach as in the other installation guides for setting up devices +* i) Generate a passcode. On the _original_ client machine, run + +``` +~/.local/bin/at_activate otp -a @_client +``` + +* ii) Make an authorization request. On the _new_ client machine, run + +``` +~/.local/bin/at_activate enroll -a @_client \ + -s \ + -p noports \ + -k ~/.atsign/keys/@_key.atKeys \ + -d \ + -n "sshnp:rw,sshrvd:rw" +``` + +* iii) Approve the authorization request. On the _original_ client machine, run + +``` +~/.local/bin/at_activate approve -a @_client \ + --arx noports \ + --drx +``` + +### **2) Copy the cryptographic keys from the machine where it's been activated in the past (Not recommended)** + +* The atSign keys file will be located at `~/.atsign/keys/` directory with a filename that will include the atSign. Copy this file from your other machine to the same location on the machine that you are installing SSH No Ports on, using `scp` or similar. + +Why don't we recommend this approach? + +> When you use method 1, it creates a new set of cryptographic keys. These keys can be disabled individually, which means if a device's keys are compromised, you can disable those keys without affecting your other devices. diff --git a/docs/installation-faq/why-activate-the-device-atsign-on-the-client.md b/docs/installation-faq/why-activate-the-device-atsign-on-the-client.md new file mode 100644 index 000000000..77a3ec67c --- /dev/null +++ b/docs/installation-faq/why-activate-the-device-atsign-on-the-client.md @@ -0,0 +1,18 @@ +--- +icon: computer +--- + +# Why activate the device atSign on the client? + +When you activate an atSign, you are doing a handful of steps to prepare the atSign for use. One of these steps is cutting a unique set of cryptographic keys. + +The first time you activate, this set of keys that gets generated is a set of management keys. These keys have full permissions to your atServer, the personalized service which powers your atSign. + +We recommend cutting the management keys on the client for a few reasons: + +1. It's extremely important that you don't lose these keys: + 1. They are less likely to get lost on your client machine than on your device. + 2. If a device is stolen you still have your management keys to recover from the theft. +2. For each device we can issue it's own set of cryptographic keys which has a few perks: + 1. This allows us to limit the permissions of those keys to the bare minimum required for NoPorts. + 2. If a device gets compromised, we can safely revoke that set of cryptographic keys, and limit the impact to your other devices. diff --git a/docs/installation/README.md b/docs/installation/README.md index 2f9cd7042..c6e95f291 100644 --- a/docs/installation/README.md +++ b/docs/installation/README.md @@ -1,14 +1,18 @@ --- icon: desktop-arrow-down +description: >- + On this page you will find instructions on how to get started with NoPorts and + set up secure remote access. Installation guides are also provided for each + Operating System. Let's get started! --- # Installation -## Overview +## Installation Overview -Installing NoPorts consists of the following steps: +To complete an installation of NoPorts and set up remote access from a client to a remote device, we must perform an installation on both the client and device machines. We will also obtain two atSigns during registration: one client atSign and one device atSign. Once we have the client and device atSigns, we are ready to begin installation. -1. [Obtain your NoPorts license](./#id-1.-obtain-your-license) from [noports.com](https://my.noports.com/no-ports-invite/14dayfreetrial)\ +1. [Obtain your NoPorts license](./#id-1.-obtain-your-license) from [noports.com](https://my.noports.com/no-ports-invite/30dayfreetrial)\ &#xNAN;_You can start with a 30-day evaluation license, no credit-card required_ 2. [Install NoPorts](./#id-2.-install-noports) software on your devices 1. Install the NoPorts client\ @@ -21,81 +25,102 @@ Installing NoPorts consists of the following steps: 4. Reach out to us\ We want to hear about your use-cases. We take all feedback into consideration, it helps us make the best tool we possibly can. -## 1. Obtain your license +The Client is defined as the machine where we are launching the remote access from. The Device is defined as the remote device that we are connecting to. -You will need to register from noports.com. +* Client installation has two options: Desktop App or CLI +* Device installation is CLI only -{% hint style="info" %} -During registration, you will receive two atSigns, these are the identifiers that you will need to setup and use NoPorts, make sure to save them somewhere for later -{% endhint %} +In summary, Installing and using NoPorts consists of the following steps: + +1. Obtain NoPorts License and atSigns +2. Install the NoPorts Client on the client machine + 1. Register the client atSign + 2. Register device atSign +3. Install the NoPorts Daemon on the remote device + 1. Repeat for multiple devices -There are two options for registration: +Once NoPorts is installed you will be able to utilize it for any TCP connections such as remote access via SSH and RDP etc! Please see the complete instructions below: -1. [Sign up for the 30-day evaluation](https://my.noports.com/no-ports-invite/30dayfreetrial). -2. Select from one of our [paid packages](https://my.noports.com/no-ports-plans). +## 1. Obtain NoPorts License and atSigns -## 2. Install the NoPorts client +To begin, you will need a NoPorts subscription or Free Trial -We have several installation options available depending on the platform and use case: +1. [Purchase NoPorts](https://my.noports.com/no-ports-plans) +2. Or, [Activate a Free Trial](https://my.noports.com/no-ports-invite/30dayfreetrial) -### 2.1. Install for the command line +{% hint style="info" %} +During registration, you will receive your client and device atSigns. Ensure you make note of them for future reference. +{% endhint %} + +## 2. Install the NoPorts Client on the client machine + +{% hint style="info" %} +If this is your first time using NoPorts on Mac or Windows, we recommend getting started with the desktop app for client installation. +{% endhint %} -These guides will install the terminal based version of the NoPorts client: +### MacOS: Choose Desktop App or CLI installation for the client -{% content-ref url="linux/" %} -[linux](linux/) +{% content-ref url="macos/desktop.md" %} +[desktop.md](macos/desktop.md) {% endcontent-ref %} -{% content-ref url="windows.md" %} -[windows.md](windows.md) +{% content-ref url="macos/cli-client.md" %} +[cli-client.md](macos/cli-client.md) {% endcontent-ref %} -### 2.2. Desktop application installation guides +### Linux: CLI only -We have two desktop applications available for NoPorts: +{% content-ref url="linux/cli-client.md" %} +[cli-client.md](linux/cli-client.md) +{% endcontent-ref %} -#### NoPorts Desktop (coming soon) +### Windows: Choose Desktop App or CLI installation for the client -This version of NoPorts supports all single-socket[^1] TCP applications, such as: +{% content-ref url="windows/desktop.md" %} +[desktop.md](windows/desktop.md) +{% endcontent-ref %} -* Remote desktop like RDP & VNC -* HTTP(s) like REST APIs & web applications -* [File sharing with SMB](#user-content-fn-2)[^2] -* [Many more use-cases](#user-content-fn-3)[^3] +{% content-ref url="windows/cli-client.md" %} +[cli-client.md](windows/cli-client.md) +{% endcontent-ref %} -The application is currently in alpha. If you would like early access, please reach out to [info@noports.com](mailto:info@noports.com). +## 3. Install the NoPorts Daemon on the remote device -#### **SSH NoPorts** +### MacOS -This version of NoPorts only supports SSH, with terminal windows embedded into the app. +{% content-ref url="macos/device.md" %} +[device.md](macos/device.md) +{% endcontent-ref %} -* [MacOS](https://apps.apple.com/us/app/ssh-no-ports-desktop/id6476198591?mt=12) -* [Windows](https://apps.microsoft.com/detail/9pbx5vrvqc2z) -* Linux - we don't have official builds, but you can [build from source](https://github.com/atsign-foundation/noports/tree/trunk/packages/dart/sshnoports)\ - [Reach out to us](mailto:support@noports.com) if you need some assistance. +### Linux: -## 3. Install the NoPorts daemon +{% content-ref url="linux/device.md" %} +[device.md](linux/device.md) +{% endcontent-ref %} -### 3.1. Use the guided installer (recommended) +### Windows: -These guides will help you use the guided installer to install the NoPorts daemon. +{% content-ref url="windows/device.md" %} +[device.md](windows/device.md) +{% endcontent-ref %} -{% hint style="info" %} -These use the same installers as the command-line client.\ -Don't worry! You have the right installer. -{% endhint %} +#### This concludes the installation instructions and you are now ready to use NoPorts for secure remote access! -{% content-ref url="linux/" %} -[linux](linux/) -{% endcontent-ref %} +## Use NoPorts + +Start by exploring the use-cases available in the side bar such as SSH, RDP, SFTP, Web Server, and SMB. We also provide in-depth usage information here: -{% content-ref url="windows.md" %} -[windows.md](windows.md) +{% content-ref url="../usage/" %} +[usage](../usage/) {% endcontent-ref %} -### 3.2. Manual installation guides +## Other Installation Guides: -These are supplementary guides, which involve some manual work. You may require this in a bespoke environment, but we recommend using the [automated installation guides](./#id-2.1.-automated-installation-guides-recommended) whenever possible. +We have additional installation guides below if you are looking for more advanced/custom installations, or installing NoPorts as part of creating a new virtual machine. + +### Manual Installation Guides + +These are supplementary guides, which involve some manual work. {% content-ref url="advanced-installation-guides/" %} [advanced-installation-guides](advanced-installation-guides/) @@ -105,7 +130,7 @@ These are supplementary guides, which involve some manual work. You may require [ipfire.md](custom-os-device-installs/ipfire.md) {% endcontent-ref %} -### 3.3. Cloud installation guides +### Cloud Installation Guides These guides will show you how to install NoPorts as part of creating a new VM. @@ -125,18 +150,3 @@ These guides will show you how to install NoPorts as part of creating a new VM. [automated-installation-on-oracle-cloud-infrastructure-oci.md](cloud-installation-guides/automated-installation-on-oracle-cloud-infrastructure-oci.md) {% endcontent-ref %} - - -## 4. Use NoPorts - -Start by exploring the use-cases available in the side bar. We also provide in-depth usage information: - -{% content-ref url="../usage/" %} -[usage](../usage/) -{% endcontent-ref %} - -[^1]: There are some multi-socket use-cases which also work. If you have a use-case please reach out to us. - -[^2]: Currently not supported on Windows due to OS specific limitations. - -[^3]: Please reach out to us, we would love to help make your use-case possible. diff --git a/docs/installation/advanced-installation-guides/README.md b/docs/installation/advanced-installation-guides/README.md index d2dc88ace..712d06a96 100644 --- a/docs/installation/advanced-installation-guides/README.md +++ b/docs/installation/advanced-installation-guides/README.md @@ -4,6 +4,8 @@ icon: wrench # Manual Installation Guides +These guides also use shell scripts for installation, but they require manual invocation. If you want a truly manual process + ### Device Side {% content-ref url="device-installation-sshnpd/" %} diff --git a/docs/installation/advanced-installation-guides/device-installation-sshnpd/README.md b/docs/installation/advanced-installation-guides/device-installation-sshnpd/README.md index adeb18adf..3651ccfb9 100644 --- a/docs/installation/advanced-installation-guides/device-installation-sshnpd/README.md +++ b/docs/installation/advanced-installation-guides/device-installation-sshnpd/README.md @@ -6,16 +6,11 @@ icon: server ## Overview -The SSH No Ports daemon (a.k.a. sshnpd) is installable as a background service in many ways depending on your environment you can choice your best option. The service may be installed as a `systemd unit`, `docker container`, `tmux session`, or as a background job using `cron` and `nohup`. The binaries can also be installed standalone so that you can install your own custom background service. +The NoPorts daemon (a.k.a. sshnpd) is installable as a background service in many ways depending on your environment you can choice your best option. The service may be installed as a `systemd unit`, `docker container`, `tmux session`, or as a background job using `cron` and `nohup`. The binaries can also be installed standalone so that you can install your own custom background service. -### No Windows Support +### :warning: This guide doesn't support Windows -We currently don't offer sshnpd as part of our releases. \ -If this is something you would like for us to prioritize, please let us know through one of the following options: - -* Create a new [GitHub issue](https://github.com/atsign-foundation/noports/issues/new/choose) -* Join [our discord](https://discord.atsign.com) and post to our `📑｜forum` channel -* [Contact support via email](mailto:support@noports.com) +On windows, we strongly recommend sticking to our automated installation process on Windows. This is because properly installing NoPorts as a Windows service requires making entries in the registry. If you want to create a custom installer for your organization, please speak to us directly at [info@noports.com](mailto:info@noports.com). ## 1. Download @@ -23,14 +18,9 @@ If this is something you would like for us to prioritize, please let us know thr You can [download a release from GitHub](https://github.com/atsign-foundation/noports/releases/), or see the table below to download the latest release for your platform. -| Platform | Linux | macOS | -| -------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| x64 | [sshnp-linux-x64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-x64.tgz) | [sshnp-macos-x64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-x64.zip) (intel) | -| arm64 | [sshnp-linux-arm64.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm64.tgz) | [sshnp-macos-arm64.zip](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-macos-arm64.zip) (apple) | -| arm | [sshnp-linux-arm.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-arm.tgz) | | -| risc-v | [sshnp-linux-riscv.tgz](https://github.com/atsign-foundation/noports/releases/latest/download/sshnp-linux-riscv.tgz) | | +{% include "../../../.gitbook/includes/linux-macos-release-table.md" %} -### 1.b. Download using curl +### 1.b. Download using curl Alternatively, if you want to download from the command line, you can do so with curl. @@ -98,4 +88,4 @@ unzip sshnp.zip See the links in the table below to continue with the installation process. -
Installation methodWhen to use this method
tmux-session.mdYou have tmux installed, or can install it. (recommended)
headless.mdIf you do not have root access and cannot install tmux
systemd-unit.mdYou are on Linux and have root access. (Here be dragons!)
standalone-binaries.mdYou want to manually setup the background service after downloading the binaries. (roll your own)
+
Installation methodWhen to use this method
systemd-unit.mdYou are on Linux and have root access. (Recommended)
tmux-session.mdYou have tmux installed, or can install it. (Deprecated)
headless.mdIf you do not have root access and cannot install tmux (Deprecated)
standalone-binaries.mdYou want to manually setup the background service after downloading the binaries. (roll your own)
diff --git a/docs/installation/available-releases.md b/docs/installation/available-releases.md new file mode 100644 index 000000000..d1458eb23 --- /dev/null +++ b/docs/installation/available-releases.md @@ -0,0 +1,34 @@ +--- +icon: table-rows +--- + +# Available Releases + +{% hint style="info" %} +In most cases, you will want to see our [.](./ "mention") page. Here, we've provided a list of all of our releases for visibility, but these links do not provide installation information. +{% endhint %} + +### Stable Releases + +We recommend choosing a release from stable, if there's one available that's supported on your platform. + +#### Desktop App + +Our dedicated desktop app is preferred in most cases. + +If your use case is primarily SSH, we recommend using sshnp from the [#cli-binaries](available-releases.md#cli-binaries "mention") section. + +{% include "../.gitbook/includes/desktop-app-release-table.md" %} + +#### Cli Binaries + +This includes all binaries for NoPorts. + +{% include "../.gitbook/includes/dart-binary-releases-table.md" %} + +### Beta Releases + +These releases are subject to potential instability or breaking changes as we mature the product-line. + +(New products coming soon!) + diff --git a/docs/installation/cloud-installation-guides/README.md b/docs/installation/cloud-installation-guides/README.md index 9dc7acf56..5b66e4c96 100644 --- a/docs/installation/cloud-installation-guides/README.md +++ b/docs/installation/cloud-installation-guides/README.md @@ -5,6 +5,10 @@ description: How to install NoPorts as part of creating a new VM # Cloud Installation Guides +{% hint style="info" %} +This is a generic cloud-init guide, we also have some [cloud specific guides](./#cloud-specific-guides) below +{% endhint %} + The NoPorts daemon can be installed on a Linux cloud virtual machine (VM) using a cloud-init script of the form: ```bash diff --git a/docs/installation/desktop-app-installation-macos-and-windows.md b/docs/installation/desktop-app-installation-macos-and-windows.md new file mode 100644 index 000000000..c69672cb4 --- /dev/null +++ b/docs/installation/desktop-app-installation-macos-and-windows.md @@ -0,0 +1,36 @@ +--- +hidden: true +--- + +# Desktop App Installation (MacOS & Windows) + +{% embed url="https://vimeo.com/1038239765" %} + +## :desktop: Desktop App Installation Instructions + +1. To begin you will need a NoPorts subscription or Free Trial + 1. [Purchase NoPorts](https://www.noports.com/pricing) + 2. Or, [Activate a Free Trial](https://my.noports.com/no-ports-invite/30dayfreetrial) +2. Note your client atsign (i.e. @name\_client) +3. Download the NoPorts Desktop App + 1. Windows Installer + 2. Mac Installer +4. Run the installer to install the NoPorts Desktop +5. Login to the No Ports Desktop App + 1. Launch the No Ports Desktop App + 2. Click the 'Get Started button' + 3. Enter your client atSign + 4. Enter one time password (OTP) +6. Backup your Keys + 1. Click on the Settings gear box button on the top right of the UI + 2. Click on the 'Backup your keys' button on the left hand navigation + 3. Download the Keys to your selected local storage location +7. Prepare a Profile to establish a NoPorts connection + 1. Return to the Dashboard + 2. Click the 'Add New' button to create a new Profile + 3. Or, Download a test profile to establish a test connection + 1. Link to test profile + 2. Upload the profile via the Dashboard +8. Click the 'Connect' / Play button for the profile you just added +9. Confirm the connection is established and utilize NoPorts for secure remote connectivity! + diff --git a/docs/installation/linux/README.md b/docs/installation/linux/README.md index 8af266f09..8a2eb7c13 100644 --- a/docs/installation/linux/README.md +++ b/docs/installation/linux/README.md @@ -1,166 +1,30 @@ --- icon: linux -description: Installation of client and server software +description: Full installation of client and server software on two Linux machines --- -# Linux & MacOS Installation Guide +# Linux Installation Guide -{% embed url="https://player.vimeo.com/video/1004237823?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0" %} +### Full Installation -For more control of the installation look at the [advanced-installation-guides](../advanced-installation-guides/ "mention"). +If you want to setup access for `Linux to Linux`, follow this guide: -| Legend | Meaning | -| ---------- | ------------------------- | -| :desktop: | Client Side | -| :printer: | Device side | -| \ | Fill in with your details | +{% content-ref url="full.md" %} +[full.md](full.md) +{% endcontent-ref %} -## :desktop: Step 1: Install on the Client machine +### Client Only Installation -{% hint style="danger" %} -If you don't own a pair of atSigns/addresses, please visit [the registrar](https://my.noports.com/no-ports-invite/14dayfreetrial) before continuing -{% endhint %} +If you want to setup access `for Linux to another OS`, follow this guide: -### (1.1) Download the Installer +{% content-ref url="cli-client.md" %} +[cli-client.md](cli-client.md) +{% endcontent-ref %} -First, make sure that you have [curl](https://curl.se) available on your system, curl is a common shell utility. +### Device Only Installation -The following command will download the `universal.sh` bash installer into your current directory: +If you want to setup access for `another OS to Linux`, first, do the client installation for the other OS, then come back here and do this installation: -```sh -curl -L https://github.com/atsign-foundation/noports/releases/latest/download/universal.sh -o universal.sh -``` - -To check if the installation downloaded correctly: - -```bash -ls | grep -w "universal.sh" -``` - -### (1.2) Run the Installer - -Make the script executable and run the script. - -```sh -chmod u+x universal.sh -./universal.sh -``` - -Type in **`client`** when asked for what type of install. Continue following along with the instructions provided with the installer until the installation is complete. - -#### Useful tips when answering the client installation - -Your client atSign should look like : `@sshnp_client` - -Your device atSign should look like: `@sshnp_device` - -[Device name](installation-details.md#device-names) should look like: `my_host, pi3, home_server_2` - -### (1.3) [Activate Client atSign (e.g. @sshnp\_client)](activating-your-atsigns.md#activate-the-client-atsign) - -This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign. - -``` -~/.local/bin/at_activate -a @_client -``` - -#### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders - -at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number. \ -\ -Once activated, the master keys will save at `~/.atsign/keys`. - -### (1.4) [Activate Device atSign (e.g. @sshnp\_device)](activating-your-atsigns.md#activate-the-device-atsign) - -This command activates your atSign and prompts you to enter an OTP. This is only done during the setup of a brand new atsign. - -``` -~/.local/bin/at_activate -a @_device -``` - -#### Enter the One Time Password (OTP) & Check your SPAM/PROMOTIONS folders - -at\_activate will pause and wait for the input of a one time pin (OTP) sent to your email or phone number. - -Once activated, the master keys will save at `~/.atsign/keys`. - -{% hint style="success" %} -Your client machine software installation is completed. Now, on to the device/server -{% endhint %} - -*** - -## :printer: Step 2 : Installing the Device - -### (2.1) Download the installer - -```bash -curl -L https://github.com/atsign-foundation/noports/releases/latest/download/universal.sh -o universal.sh -``` - -To check if the installation downloaded correctly: - -```bash -ls | grep -w "universal.sh" -``` - -### (2.2) Run the installer - -```bash -chmod u+x universal.sh -./universal.sh -``` - -The script will guide you through the installation process. It will prompt you for the information you need. Make sure you type in `device` when it asks what type of installation.\ - \ -**You will need the client atSign, device atSign and the device name. making sure they match your earlier choices.** - -*** - -## Step 3: Authorizing atSigns - -### (3.1) :desktop:: Generate a passcode - -On the **client machine**, run the following command. It should output a 6-character passcode. - -```bash -~/.local/bin/at_activate otp -a @_device -``` - -### (3.2) :printer:: Make an authorization request from your device machine - -On the **device machine**, run the following command, using the DEVICE\_NAME that you chose while running the installer earlier - -
~/.local/bin/at_activate enroll -a @<REPLACE>_device \
-  -s <PASSCODE> \
-  -p noports \
-  -k ~/.atsign/keys/@<REPLACE>_device_key.atKeys \
-  -d <DEVICE_NAME> \
-  -n "sshnp:rw,sshrvd:rw"
-
- -#### Once you see this text, you're ready to continue to the next step. - -``` -Submitting enrollment request -Enrollment ID: --------------------- -Waiting for approval; will check every 10 seconds -``` - -### (3.3) :desktop:: Approve the authorization request - -On the **client machine**, run the following command - -```bash -~/.local/bin/at_activate approve -a @_device \ - --arx noports \ - --drx -``` - -{% hint style="success" %} -Installation Complete!\ -\ -You are ready to use SSH No Ports, visit the [basic-usage-1](../../usage/basic-usage-1/ "mention"). -{% endhint %} - -### [#want-to-use-your-client-atsign-on-a-different-machine](installation-details.md#want-to-use-your-client-atsign-on-a-different-machine "mention") +{% content-ref url="device.md" %} +[device.md](device.md) +{% endcontent-ref %} diff --git a/docs/installation/linux/cli-client.md b/docs/installation/linux/cli-client.md new file mode 100644 index 000000000..6d9621083 --- /dev/null +++ b/docs/installation/linux/cli-client.md @@ -0,0 +1,21 @@ +# Linux Cli Client Installation + +{% include "../../.gitbook/includes/get-atsigns-from-reg-warning.md" %} + +### Step 1: Download the Installer + +{% include "../../.gitbook/includes/universal.sh-preamble.md" %} + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### Step 2: Run the Installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/unversal.sh-execute-client-details.md" %} + +### Step 3: Activate your client atSign + +{% include "../../.gitbook/includes/activate-cli-client-unix.md" %} + +{% include "../../.gitbook/includes/installation-complete-visit-usage.md" %} diff --git a/docs/installation/linux/device.md b/docs/installation/linux/device.md new file mode 100644 index 000000000..01fa9e103 --- /dev/null +++ b/docs/installation/linux/device.md @@ -0,0 +1,55 @@ +# Linux Device Installation + +{% include "../../.gitbook/includes/device-warning-setup-client-first.md" %} + +## Step 1 : Activate the device atSign from your `client machine` + +If you've already activated the device atSign skip to [step 2](device.md#step-2-installing-on-the-device). + +{% include "../../.gitbook/includes/device-activate-preamble.md" %} + +### (1.1) Download the activation software on the `client machine` + +{% include "../../.gitbook/includes/universal.sh-preamble.md" %} + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (1.2) Run the installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/universal.sh-execute-activate-only.md" %} + +### (1.3) Activate the device atSign from the `client machine` + +{% include "../../.gitbook/includes/activate-cli-device-unix.md" %} + +## Step 2 : Installing on the `device` + +### (2.1) Download the installer + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (2.2) Run the installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/universal.sh-execute-device-detail.md" %} + +*** + +## Step 3: Authorizing the device atSign + +### (3.1) Generate a passcode from your `client machine` + +{% include "../../.gitbook/includes/apkam-1-unix.md" %} + +### (3.2) Make an authorization request from your `device machine` + +{% include "../../.gitbook/includes/apkam-2-unix.md" %} + +### (3.3) Approve the authorization request from your `client machine` + +{% include "../../.gitbook/includes/apkam-3-unix.md" %} + +{% include "../../.gitbook/includes/installation-complete-visit-usage.md" %} diff --git a/docs/installation/linux/full.md b/docs/installation/linux/full.md new file mode 100644 index 000000000..cc371fec2 --- /dev/null +++ b/docs/installation/linux/full.md @@ -0,0 +1,63 @@ +# Linux Full Installation + +{% include "../../.gitbook/includes/mac-linux-full-install-video.md" %} + +For more control of the installation look at the [advanced-installation-guides](../advanced-installation-guides/ "mention"). + +## Step 1: Install on the `client machine` + +{% include "../../.gitbook/includes/get-atsigns-from-reg-warning.md" %} + +### (1.1) Download the Installer + +{% include "../../.gitbook/includes/universal.sh-preamble.md" %} + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (1.2) Run the Installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/unversal.sh-execute-client-details.md" %} + +### (1.3) Activate Client atSign + +{% include "../../.gitbook/includes/activate-cli-client-unix.md" %} + +### (1.4) Activate Device atSign + +{% include "../../.gitbook/includes/activate-cli-device-unix.md" %} + +{% include "../../.gitbook/includes/client-installation-complete.md" %} + +*** + +## Step 2 : Installing on the `device` + +### (2.1) Download the installer + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (2.2) Run the installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/universal.sh-execute-device-detail.md" %} + +*** + +## Step 3: Authorizing atSigns + +### (3.1) Generate a passcode from your `client machine` + +{% include "../../.gitbook/includes/apkam-1-unix.md" %} + +### (3.2) Make an authorization request from your `device machine` + +{% include "../../.gitbook/includes/apkam-2-unix.md" %} + +### (3.3) Approve the authorization request from your `client machine` + +{% include "../../.gitbook/includes/apkam-3-unix.md" %} + +{% include "../../.gitbook/includes/installation-complete-visit-usage.md" %} diff --git a/docs/installation/linux/installation-details.md b/docs/installation/linux/installation-details.md deleted file mode 100644 index dd5ef59cc..000000000 --- a/docs/installation/linux/installation-details.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -icon: memo-circle-info ---- - -# Installation Details - -## Device Names - -Each device atSign can be used for multiple devices and so each device needs a unique name. The device name is limited to alphanumeric [snake case](https://www.tuple.nl/knowledge-base/snake-case) (lowercase alphanumeric separated by \_ ) up to 36 characters. - -Example snake case device names - -``` -my_host -canary02 -oci_mail_0001 -dc_001_row_009_rack_0067_ru_014 -``` - -## SSH Keys - -SSH uses keys to authenticate as well as having a fallback of using passwords, but using keys is easier and more secure than "mypassword!". If you already are a seasoned user of SSH then you might have keys already but if not then on the client machine you can create a key pair using ssh-keygen. - -Example ssh-keygen command to create SSH Key Pair - -``` -ssh-keygen -t ed25519 -a 100 -f ~/.ssh/id_ed25519 -``` - -## Want to use your client atSign on a different machine? - -You can either: - -1. Generate a new set of cryptographic keys (Recommended), or -2. Copy the cryptographic keys from the machine where it's been activated in the past (Not recommended) - -**1) Generate a new set of cryptographic keys (Recommended)** - -* We use the same approach as in the "Authorize the device to use the device atSign" section above -* i) Generate a passcode. On the _original_ client machine, run - -``` -~/.local/bin/at_activate otp -a @_client -``` - -* ii) Make an authorization request. On the _new_ client machine, run - -``` -~/.local/bin/at_activate enroll -a @_client \ - -s \ - -p noports \ - -k ~/.atsign/keys/@_key.atKeys \ - -d \ - -n "sshnp:rw,sshrvd:rw" -``` - -* iii) Approve the authorization request. On the _original_ client machine, run - -``` -~/.local/bin/at_activate approve -a @_client \ - --arx noports \ - --drx -``` - -**2) (Not recommended) Copy the cryptographic keys from the machine where it's been activated in the past** - -* The atSign keys file will be located at `~/.atsign/keys/` directory with a filename that will include the atSign. Copy this file from your other machine to the same location on the machine that you are installing SSH No Ports on, using `scp` or similar. diff --git a/docs/installation/macos/README.md b/docs/installation/macos/README.md new file mode 100644 index 000000000..fd2bcd5df --- /dev/null +++ b/docs/installation/macos/README.md @@ -0,0 +1,29 @@ +--- +icon: apple +--- + +# MacOS Installation Guides + +### Desktop App Installation + +If this is your first time using NoPorts, we recommend you start here: + +{% content-ref url="desktop.md" %} +[desktop.md](desktop.md) +{% endcontent-ref %} + +### CLI Client Installation + +If you are more comfortable with the CLI, you can follow this guide to install the binaries: + +{% content-ref url="cli-client.md" %} +[cli-client.md](cli-client.md) +{% endcontent-ref %} + +### Device Installation + +If you want to setup access to your MacOS device, follow this guide: + +{% content-ref url="device.md" %} +[device.md](device.md) +{% endcontent-ref %} diff --git a/docs/installation/macos/cli-client.md b/docs/installation/macos/cli-client.md new file mode 100644 index 000000000..8992468a6 --- /dev/null +++ b/docs/installation/macos/cli-client.md @@ -0,0 +1,25 @@ +# MacOS CLI Client Installation + +{% include "../../.gitbook/includes/get-atsigns-from-reg-warning.md" %} + +### Step 1: Download the Installer + +{% include "../../.gitbook/includes/universal.sh-preamble.md" %} + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### Step 2: Run the Installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/unversal.sh-execute-client-details.md" %} + +### Step 3: Activate your client atSign + +{% hint style="warning" %} +If you've activated your **client** atSign on another device already, this step will not work. Instead, follow this guide: [reuse-your-client-atsign-on-another-machine.md](../../installation-faq/reuse-your-client-atsign-on-another-machine.md "mention") +{% endhint %} + +{% include "../../.gitbook/includes/activate-cli-client-unix.md" %} + +{% include "../../.gitbook/includes/installation-complete-visit-usage.md" %} diff --git a/docs/installation/macos/desktop.md b/docs/installation/macos/desktop.md new file mode 100644 index 000000000..6df22456b --- /dev/null +++ b/docs/installation/macos/desktop.md @@ -0,0 +1,52 @@ +--- +description: >- + Before beginning installation, you must have already registered at noports.com + and obtained your client and device atSigns. +--- + +# MacOS Desktop Client Installation + + + +{% embed url="https://vimeo.com/1038239765" %} + +### :desktop: MacOS Desktop App Client Installation Instructions + +1. Note your client atSign (i.e. @name\_client) + 1. Client atSign is used to login and will automatically be activated once used to login to the desktop app + 2. Device atSign will need to be activated via CLI (instructions under MacOS Device Installation)\ + +2. Download the NoPorts Desktop App + 1. [Link to Apple Store](https://apps.apple.com/ca/app/noports-desktop/id6737338881)\ + +3. Run the installer to install the NoPorts Desktop\ + +4. Login to the NoPorts Desktop App + 1. Launch the NoPorts Desktop App + 2. Click the 'Get Started button' + 3. Enter your client atSign + 1. This also registers the client atSign + 4. Enter one time password (OTP)\ + +5. Back up your Keys + 1. Click on the Settings gear box button on the top right of the UI + 2. Click on the 'Back up your keys' button on the left hand navigation + 3. Download the Keys to your selected local storage location\ + +6. Prepare a Profile to establish a NoPorts connection + 1. Return to the Dashboard + 2. Click the 'Add New' button to create a new Profile + 1. Enter the details for the new profile + 3. Or, Download a test profile to establish a test connection + 1. [Link to test profile](https://drive.google.com/file/d/1qb0YrpRaGstLSBKoLJ4wwVUIMO5zCaMq/view?usp=sharing) + 2. Upload the profile via the Dashboard + 3. Start the connection by pressing :arrow\_forward: + 4. Connect to [http://localhost:8080](http://localhost:8080) in your browser + 5. Congrats, you just connected to a secret webpage via NoPorts! +7. Click the 'Connect' / Play button for the profile you just added + +{% hint style="info" %} +\*Note, your remote device installation must be complete before the profile will connect. If utilizing a test profile, it will connect to our test site without needing a remote device to be set up first. +{% endhint %} + +8. Confirm the connection is established and utilize NoPorts for secure remote connectivity! diff --git a/docs/installation/macos/device.md b/docs/installation/macos/device.md new file mode 100644 index 000000000..bfcd38b0b --- /dev/null +++ b/docs/installation/macos/device.md @@ -0,0 +1,55 @@ +# MacOS Device Installation + +{% include "../../.gitbook/includes/device-warning-setup-client-first.md" %} + +## Step 1 : Activate the device atSign from your `client machine` + +If you've already activated the device atSign skip to [step 2](device.md#step-2-installing-on-the-device). + +{% include "../../.gitbook/includes/device-activate-preamble.md" %} + +### (1.1) Download the activation software on the `client machine` + +{% include "../../.gitbook/includes/universal.sh-preamble.md" %} + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (1.2) Run the installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/universal.sh-execute-activate-only.md" %} + +### (1.3) Activate the device atSign from the `client machine` + +{% include "../../.gitbook/includes/activate-cli-device-unix.md" %} + +## Step 2 : Installing on the `device` + +### (2.1) Download the installer + +{% include "../../.gitbook/includes/universal.sh-download-command.md" %} + +### (2.2) Run the installer + +{% include "../../.gitbook/includes/universal.sh-execute.md" %} + +{% include "../../.gitbook/includes/universal.sh-execute-device-detail.md" %} + +*** + +## Step 3: Authorizing the device atSign + +### (3.1) Generate a passcode from your `client machine` + +{% include "../../.gitbook/includes/apkam-1-unix.md" %} + +### (3.2) Make an authorization request from your `device machine` + +{% include "../../.gitbook/includes/apkam-2-unix.md" %} + +### (3.3) Approve the authorization request from your `client machine` + +{% include "../../.gitbook/includes/apkam-3-unix.md" %} + +{% include "../../.gitbook/includes/installation-complete-visit-usage.md" %} diff --git a/docs/installation/quick-start-for-macos-and-windows.md b/docs/installation/quick-start-for-macos-and-windows.md new file mode 100644 index 000000000..c3f638af4 --- /dev/null +++ b/docs/installation/quick-start-for-macos-and-windows.md @@ -0,0 +1,49 @@ +--- +icon: forward +--- + +# Quick Start for MacOS and Windows + +## 1. Sign up for a NoPorts free trial + +Go to [noports.com](https://my.noports.com/no-ports-invite/30dayfreetrial) and sign up for a 30-day free trial. + +{% hint style="info" %} +Make note of your client atSign (e.g., @pluto83\_client). You'll need it shortly. +{% endhint %} + +## 2. Download the NoPorts desktop application + +Download the NoPorts desktop app using one of the links below: + +[Link to Apple Store](https://apps.apple.com/ca/app/noports-desktop/id6737338881) + +[Link to Windows Store](https://apps.microsoft.com/detail/9n69scrrgv6r) + +{% hint style="info" %} +For Linux please follow the [Linux Installation Guide](https://docs.noports.com/installation/linux). +{% endhint %} + +## 3. Log into the NoPorts desktop application + +1. Launch the NoPorts desktop app and click **Get Started**. +2. Enter your **client atSign** into the text field (e.g., @pluto83\_client), leave the root domain as is, and then click **Next**. +3. A **one-time password (OTP)** will be sent to you via email. Enter this OTP into the app and then click **Confirm**. + +## 4. Save a copy of your atKeys + +Your atKeys (cryptographic keys) will be used to pair your atSign with this and other devices in future. You can [learn more about these keys here](../installation-faq/why-activate-the-device-atsign-on-the-client.md). + +1. Click on the **Settings Icon** in the top right corner of the app. +2. Click on **Back Up Your Keys** in the left navigation panel. +3. Select a location on your device and **save** your keys. + +## 5. Set up a test connection + +1. Download the[ NoPorts test connection profile. ](https://drive.google.com/file/d/1qb0YrpRaGstLSBKoLJ4wwVUIMO5zCaMq/view)This is a json file containing connection details for a test profile we have created. +2. Return to the NoPorts app **Dashboard**. +3. Click **Import** and select the test connection profile that you just downloaded. +4. Click the **Connect Icon ▶️** to establish a connection. +5. Open a web browser and navigate to`http://localhost:8080`. + +Congratulations! You're connected to a hidden webpage via NoPorts! diff --git a/docs/installation/windows.md b/docs/installation/windows.md deleted file mode 100644 index a5d02a9a4..000000000 --- a/docs/installation/windows.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -icon: windows -description: SSH No Ports Windows ---- - -# Windows Installation Guide - -### Installation - -First, open a powershell terminal. - -Then run the following command: - -```powershell -Invoke-WebRequest -Uri "https://github.com/atsign-foundation/noports/releases/latest/download/universal.ps1" -OutFile "universal.ps1" -``` - -#### Running the installer - -After downloading the installer, you can run the installer by running the following command: - -```powershell -.\universal.ps1 -``` - -#### Device Side - -After finishing the device install, you will have a windows service installed called `sshnpd`. This service will be started automatically and will be running in the background. - -#### Client Side - -After finishing the client install, you will have a binary called `{device_name@device_atsign}` installed on your machine. You can use this binary to connect to the device. - -Example: - -```powershell -esp_32@wanderinggazebo -``` - -or - -``` -.\esp_32@wanderinggazebo.ps1 -``` - -### SSH Key Generation - -To generate an SSH key, you can run the following command: - -For RSA: - -```powershell -ssh-keygen -``` - -For Ed25519: - -```powershell -ssh-keygen -t ed25519 -``` - -### Activate the device atSign - -First time activating this atSign - -```powershell -at_activate onboard -a "@_device" -``` - -or - -
Users\<user>\.local\bin\at_activate onboard -a "<REPLACE>_device"
-
- -\ -Activated this atSign before ? As before if this atSign is already activated elsewhere then you need to copy the .atKeys file for this atSign into the \~/.atsign/keys/ directory. - -### RDP? Check this out. - -{% content-ref url="../use-cases/rdp.md" %} -[rdp.md](../use-cases/rdp.md) -{% endcontent-ref %} - -[^1]: replace diff --git a/docs/installation/windows/README.md b/docs/installation/windows/README.md new file mode 100644 index 000000000..2fcd5544d --- /dev/null +++ b/docs/installation/windows/README.md @@ -0,0 +1,19 @@ +--- +icon: windows +--- + +# Windows Installation Guide + +Desktop App Installation + +If this is your first time using NoPorts, we recommend you start here: + +{% content-ref url="desktop.md" %} +[desktop.md](desktop.md) +{% endcontent-ref %} + +### :warning: CLI Client & Device Support Coming soon + +Outside of the desktop app, the current installer for Windows is an unstable method, and has limited support. + +We are in the process of building a better installer for Windows, when that becomes available, this page will include those installation methods. If you would like early access to that installer, please contact us at [info@noports.com](mailto:info@noports.com). diff --git a/docs/installation/windows/cli-client.md b/docs/installation/windows/cli-client.md new file mode 100644 index 000000000..c56599ec3 --- /dev/null +++ b/docs/installation/windows/cli-client.md @@ -0,0 +1,5 @@ +# Windows CLI Client Installation + +{% hint style="warning" %} +Official support coming soon! +{% endhint %} diff --git a/docs/installation/windows/desktop.md b/docs/installation/windows/desktop.md new file mode 100644 index 000000000..550c90ff6 --- /dev/null +++ b/docs/installation/windows/desktop.md @@ -0,0 +1,50 @@ +--- +description: >- + Before beginning installation, you must have already registered at noports.com + and obtained your client and device atSigns. +--- + +# Windows Desktop Client Installation + +{% embed url="https://vimeo.com/1038239765" %} + +### :desktop: Windows Desktop App Client Installation Instructions + +1. Note your client atSign (i.e. @name\_client) + 1. Client atSign is used to login and will automatically be activated once used to login to the desktop app + 2. Device atSign will need to be activated via CLI (instructions under Windows Device Installation)\ + +2. Download the NoPorts Desktop App + 1. [Link to Windows Store](https://apps.microsoft.com/detail/9n69scrrgv6r)\ + +3. Run the installer to install the NoPorts Desktop\ + +4. Login to the NoPorts Desktop App + 1. Launch the NoPorts Desktop App + 2. Click the 'Get Started button' + 3. Enter your client atSign + 4. Enter one time password (OTP)\ + +5. Back up your Keys + 1. Click on the Settings gear box button on the top right of the UI + 2. Click on the 'Back up your keys' button on the left hand navigation + 3. Download the Keys to your selected local storage location\ + +6. Prepare a Profile to establish a NoPorts connection + 1. Return to the Dashboard + 2. Click the 'Add New' button to create a new Profile + 1. Enter the details for the new profile + 3. Or, Download the test profile to establish a test connection + 1. [Link to test profile](https://drive.google.com/file/d/1qb0YrpRaGstLSBKoLJ4wwVUIMO5zCaMq/view?usp=sharing) + 2. Upload the profile via the Dashboard + 3. Start the connection by pressing :arrow\_forward: + 4. Connect to [http://localhost:8080](http://localhost:8080) in your browser + 5. Congrats, you just connected to a secret webpage via NoPorts!\ + +7. Click the 'Connect' / Play button for the profile you just added + +{% hint style="info" %} +\*Note, your remote device installation must be complete before the profile will connect. If utilizing a test profile, it will connect to our test site without needing a remote device to be set up first. +{% endhint %} + +8. Confirm the connection is established and utilize NoPorts for secure remote connectivity! diff --git a/docs/installation/windows/device.md b/docs/installation/windows/device.md new file mode 100644 index 000000000..96d872216 --- /dev/null +++ b/docs/installation/windows/device.md @@ -0,0 +1,5 @@ +# Windows Device Installation + +{% hint style="warning" %} +Official support coming soon! +{% endhint %} diff --git a/docs/reference/how-it-works.md b/docs/reference/how-it-works.md index 173eca2b0..5995bfc14 100644 --- a/docs/reference/how-it-works.md +++ b/docs/reference/how-it-works.md @@ -1,47 +1,45 @@ --- icon: magnifying-glass -description: >- - SSH No Ports uses Atsign’s end-to-end encrypted control plane to initiate SSH - connections without opening ports on either of your devices. --- # How It Works -## **Atsign’s Core Technology (a.k.a. Control Plane)** +**What is NoPorts?** NoPorts is a zero trust security tool that uses Atsign's atPlatform to initiate connections without opening ports on either of your devices. It creates a privacy-first environment, and completely removes network attack surfaces. NoPorts is already being used in the field to do things like [replace VPNs and firewalls](https://www.noports.com/use-cases/vpn-replacement), and enable [zero trust remote access](https://www.noports.com/use-cases/remote-access). -1. **Addressability**\ - Atsign’s core technology uses identifiers which replace the need to manage IP addresses. If you remember the atSign (Atsign’s version of an address), you can look up the IP address and port in the atDirectory which manages this information for you. -2. **Reachability**\ - **‍**Atsign’s core technology provides each device with its own microservice which makes it reachable from anywhere on the Internet. -3. **No open ports (no network attack surface) on the device**\ - Connections are always made from the device to the microservice, meaning that no ports ever need to be opened on devices using this technology. -4. **End-to-end encrypted**\ - Information is automatically encrypted on the edge devices before it is sent over Atsign’s control plane. -5. **Zero Trust**\ - Atsign’s technology is designed so that cryptographic keys are only stored on the edge device. No third party or intermediary ever possesses the decryption keys which are required to access the information. You don’t need to trust any of the microservices, because they never see information in the clear. +**How does this technology work?** In the simplest explanation, NoPorts utilizes the atPlatform and atSigns to create an encrypted connection between devices over TCP/IP. An intriguing part of this technology is that TCP ports are not open on the endpoints, and the connection is completely invisible to prying eyes with no entry-point for cybersecurity attacks. Any device or application sitting behind NoPorts has no open ports, no static IP address required, and cannot be digitally hacked! This a huge leap forward in cybersecurity as there are no other solutions that can provide this level of system security. Pretty awesome right? We think so too!\ +\ +To further our understanding of how zero trust security is established via NoPorts, let’s briefly discuss the function of an atSign. Then, we can explore the connectivity process with easy to follow diagrams. An atSign is a resolvable address assigned to a device, person, an entire organization, or anything you like. For example, @alice could be an atSign for a person named Alice. An atSign is used to securely exchange information without any chance of surveillance, impersonation, or theft. -## **How SSH No Ports uses Atsign’s Control Plane & Policy Plane** +Now, let’s look at a diagram of a completed atSign/NoPorts connection between two devices. -
+
-

Planes of the atPlatform

+In the diagram, you can see two devices connected with atSigns (@PointA and @PointB). The connection is established without having any open external ports on the client or remote machine and any TCP application can be setup to utilize a NoPorts connection. Because all ports are closed, the atSign encrypted tunnel is set up with outbound requests only which are sent to an atServer. -
+Now, let’s discuss what an atServer is and how it functions as part of the overall atPlatform topology. An atServer is responsible for managing identity and maintaining the key-value data store for each atSign. It performs cryptographic identity validation to ensure that each entity is who they claim to be, supporting secure interactions. It serves as a secure repository and only holds data that is either explicitly made public or data that is encrypted. The atServers cannot decrypt or view any encrypted data as they do not hold the keys to decrypt it. Each atSign utilizes a separate atServer, and the atServers complete the negotiation for setting up the connection between the endpoints. -1. @client makes a request to @relay for two listening TCP/IP ports -2. @client contacts @server to get status and capabilities -3. @server responds if @client is permitted to connect, permission is either given locally or via @policy -4. @client derives a new ephemeral AES 256bit key and sends the key along with the IP/DNS name and one of the ports it received from @relay plus the requested remote host:service -5. @server confirms that @client is allowed to connect and to the service requested either locally or via @policy. If permitted, then @server makes a TCP/IP connection to @relay on the specified port and authenticates -6. @client makes a connection to @relay on the other port and authenticates -7. @relay then relays the data between the two TCP connections **@relay does not have the AES key** so cannot "see" the encrypted dataflow -8. @client listens on the localhost interface of the client and encrypts any connections made to it with the ephemeral AES key from stage 4 -9. @server connects the to the required TCP/IP service requested in stage 5 and then encrypts the connection and forwards on to @relay -10. At this point a client application connects to the localhost interface on the client on the requested port and any data is encrypted and passed via @relay and on to @server then on to the listening service. +Since we now have a basic understanding of atSigns and atServers we can take a look at a more comprehensive diagram and discuss further details about the atPlatform. -If the service requested by @client was SSH on @server for example. The `ssh` command would be directed to locahost on @client and yet in fact that connection would be forward to the `sshd` daemeon on @server, via the outbound connections to @relay. +

atPlatform

-This handshake takes a few seconds to make but once established the connection is near real time. You can see the handshake happening as you use the `sshnp` or the `npt` commands and if you what to see more details then, add the `-v` flag. +**Connection Establishment** + +So, how exactly does a NoPorts connection get established and what are the steps? Let's look at a summary overview of each step in a NoPorts connection: + +1. NoPorts Client @pointA sends a request to NoPorts Relay service @relay to ask for an IP address and a pair of ports to rendezvous with Remote Machine @pointB. +2. NoPorts Relay receives the request, allocates a pair of ports on the host it is running on, responds with its IP address and the pair of ports. +3. Client receives response from Relay +4. Client sends request to the Remote Machine to connect which includes session information, the client’s intent (such as destination TCP port 3389 on localhost), and the generated public key from an ephemeral asymmetric key-pair. +5. NoPorts Daemon on Remote Machine sends request to NoPorts Policy service @policy to determine whether or not @pointA is permitted to connect to @pointB on the specified localhost port. +6. Policy service looks up information accordingly and sends response back to the daemon on Remote Machine. + 1. If request is not allowed, the daemon will not respond to the client, or send a not permitted response. + 2. If request is allowed, the daemon generates a symmetric encryption key and a socket connection to the Relay IP address and port 2. Response is sent to the Client for ‘session started’ and includes the symmetric encryption key which is encrypted with the ephemeral public key which was previously sent by the Client. +7. NoPorts daemon on Remote Machine sends response to Client as ‘session started’. +8. Client receives response and creates a socket to the Relay IP address and port 1. +9. The Relay verifies the authentication strings and joins the authenticated sockets from the Client and Remote Machine. +10. NoPorts connection established. + +And that's it! At this point, the real client application (e.g. RDP) can connect to a local port on the Client to be sent over the NoPorts connection for secure remote access to the Remote Machine. diff --git a/docs/reference/policy.md b/docs/reference/policy.md index a47fa1d3a..4d9a05e2d 100644 --- a/docs/reference/policy.md +++ b/docs/reference/policy.md @@ -2,8 +2,10 @@ icon: users-rectangle --- -# Managing Policies +# NoPorts Policy Service -NoPorts has a flexible suite of tools for managing policies. You can use a standalone database for storing and managing your policies using our administration interface, or you can integrate it with your existing policy database or service. +The NoPorts Policy Service is a flexible suite of tools for managing policies. You can use a standalone database for storing and managing your policies using our administration interface, or you can integrate it with your existing policy database or service. -The policy suite is currently in alpha status, further documentation and examples will come with the first GA release of our policy suite. +

High level overview of the NoPorts architecture

+ +The NoPorts Policy Service is currently in alpha status. [Schedule a call](https://calendly.com/noports/speak-to-an-engineer) with one of our engineers to become an alpha tester. diff --git a/docs/usage/README.md b/docs/usage/README.md index b8257eed8..6f1200f15 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -4,22 +4,28 @@ icon: person-from-portal # Usage +### Use Cases + +If you have a specific use case, we may already cover the steps you need to take. Check out these guides. + +
web-server.mdssh.md
rdp.mdsftp.md
be-your-own-vpn.mdsmb.md
+ ### Generic Usage of NoPorts +If your primary use case involves more than just SSH, start here, or check out some of our use cases below. + {% content-ref url="basic-usage/" %} [basic-usage](basic-usage/) {% endcontent-ref %} ### SSH Usage over NoPorts +If your primary use case is SSH, start here. We also recommend the ssh config integration for a seamless experience. + {% content-ref url="basic-usage-1/" %} [basic-usage-1](basic-usage-1/) {% endcontent-ref %} -{% content-ref url="quick-ssh-picker-script.md" %} -[quick-ssh-picker-script.md](quick-ssh-picker-script.md) -{% endcontent-ref %} - {% content-ref url="integrate-with-ssh-config.md" %} [integrate-with-ssh-config.md](integrate-with-ssh-config.md) {% endcontent-ref %} diff --git a/docs/usage/integrate-with-ssh-config.md b/docs/usage/integrate-with-ssh-config.md index 74e728071..3b87fbb9f 100644 --- a/docs/usage/integrate-with-ssh-config.md +++ b/docs/usage/integrate-with-ssh-config.md @@ -4,7 +4,21 @@ icon: square-sliders-vertical # Integrate with ssh config -## The Template +## Overview + +This guide will help you setup NoPorts in your ssh configuration. Once setup, you will be able to ssh to machines using NoPorts the same way you would for a normal ssh host. As this is integrated with the SSH configuration, it will also work with other applications that support SSH proxying. + +### Usage + +Once you've setup your configuration, you will be able to SSH over NoPorts just like any other host, using your own custom hostnames for devices. + +For example, with a device called `my_lab`: + +```sh +ssh my_lab +``` + +### The Template The following is a template for adding an sshnp connection to your ssh config for ease of use: @@ -23,7 +37,15 @@ Host ``` {% endcode %} -Example: +You need to replace the values surrounded with `<>` on lines 1 & 7 with your own values. + +`host` is any valid hostname you would like, this is what you will use to invoke your ssh command, so make sure it's easy to remember and type. + +`username` is the username on the remote machine you wish to login as. + +The rest of the values are the normal arguments you would invoke with sshnp, see [here](basic-usage-1/) for more info. + +#### Example {% code overflow="wrap" %} ``` @@ -39,20 +61,51 @@ Host alice_device ``` {% endcode %} +This example shows the configuration for the following equivalent sshnp command: + ``` sshnp -f @alice_client -t @alice_device -d my_server -r @rv_am ``` -### Usage +When you want to connect to this device, this is what you would type: + +```bash +ssh alice_device +``` + +`alice_device` maps the the `Host alice_device` line. + +### Additional Usage Tips + +#### 1. Extending ssh config + +You can add any additional ssh config to the file as you normally would, for example a TCP forwarding: + +{% code title="~/.ssh/config" overflow="wrap" lineNumbers="true" %} +``` +Host my_webdev_server + Hostname localhost + AddKeysToAgent yes + UserKnownHostsFile /dev/null + StrictHostKeyChecking no + IdentityFile ~/.ssh/id_ed25519 + LocalForward 8080:0:8080 + ProxyCommand=... +``` +{% endcode %} -Use this config as you would any other ssh config entry: +#### 2. Extending ssh command + +You can also add any additional flags to the ssh command, for example a TCP forwarding: ```bash -ssh +ssh my_webdev_server -L "8080:0:8080" ``` ### Template Explained +If you want to understand each line of the template, and what it does, read on. + #### Line 1 `` is the "nickname" you would use to connect to, e.g. `ssh `. @@ -91,29 +144,3 @@ See [basic-usage-1](basic-usage-1/ "mention") to learn more about filling in thi ControlMaster and ControlPath tell ssh to try to reuse existing ssh connections if you start up multiple. This means only the first connection will setup sshnp, the rest of the connections will use the tunnel that is already there! -### Additional Usage Tips - -#### 1. Extending ssh config - -You can add any additional ssh config to the file as you normally would, for example a TCP forwarding: - -{% code title="~/.ssh/config" overflow="wrap" lineNumbers="true" %} -``` -Host my_webdev_server - Hostname localhost - AddKeysToAgent yes - UserKnownHostsFile /dev/null - StrictHostKeyChecking no - IdentityFile ~/.ssh/id_ed25519 - LocalForward 8080:0:8080 - ProxyCommand=... -``` -{% endcode %} - -#### 2. Extending ssh command - -You can also add any additional flags to the ssh command, for example a TCP forwarding: - -```bash -ssh my_webdev_server -L "8080:0:8080" -``` diff --git a/docs/usage/quick-ssh-picker-script.md b/docs/usage/quick-ssh-picker-script.md deleted file mode 100644 index 327e5bbb7..000000000 --- a/docs/usage/quick-ssh-picker-script.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -description: np.sh - The quick run script -icon: list-ol ---- - -# Quick SSH picker script - -If you installed the noports client using our `universal.sh` script, you may have noticed that it installed an additional script called `np.sh`. - -This script was installed to make it slightly easier to connect to all of your devices using noports, if you are good with scripting or already have a preferred way to use noports, feel free to delete, modify or ignore this script entirely. - -{% hint style="danger" %} -If you don't have any devices configured, this script will exit. See [#configuring-np.sh](quick-ssh-picker-script.md#configuring-np.sh "mention") below to set this script up for your use. -{% endhint %} - -Here is the script template which we store in GitHub: - -{% @github-files/github-code-block url="https://github.com/atsign-foundation/noports/blob/trunk/packages/dart/sshnoports/bundles/shell/magic/sshnp.sh" %} - -### Variables in np.sh - -The idea behind configuring np.sh is to give yourself a sane set of defaults for using sshnp. You can override any of these defaults in the script by passing the flag for sshnp to np.sh. For example: - -`./np.sh -f @bob` - will replace the `client_atsign` default value with `@bob` at runtime. - -#### Configuring np.sh - -To configure np.sh, simply modify any of the variables surrounded by `SCRIPT METADATA` and `END METADATA`. - -`client_atsign` is the default atSign for the `-f` or `--from` argument in sshnp. - -`device_atsign` is the default atSign for the `-t` or `--to` argument in sshnp. - -`host_atsign` is the default atSign for the `-r` or `--srvd` argument in sshnp. - -`devices` is a bash array of all the device names you want quick access to, use a space to separate device names. - -`additional_args` is all of the additional arguments you wish to have enabled for sshnp by default, this is a good place to enable things like `-s` or `-i` or `-v` - diff --git a/docs/use-cases/web-server.md b/docs/use-cases/web-server.md index f55a9cf6a..de1a9f6e0 100644 --- a/docs/use-cases/web-server.md +++ b/docs/use-cases/web-server.md @@ -1,10 +1,11 @@ --- icon: globe-pointer +description: This guide covers usage of NoPorts with webpages or APIs. --- # Web Server -Here, we demonstrate how to use the NoPorts Tunnel to bridge a web server on a remote machine to localhost:80 so we can access the web server locally. +Here, we demonstrate how to use the NoPorts Tunnel to bridge a web server on a remote machine to localhost:80 so we can access the web server locally. {% hint style="info" %} We are assuming that the web server is running on port `8080`, you can replace it with the port that your web server is running on. (Also works over TLS with port 443)