= SSH-Conduit User Guide :ssh-conduit-page: anchor:table_of_contents[] {start-toc} [[toc]] [compact] * link:#under-toc[Conventions] * link:#_what_is_ssh_conduit[What is SSH-Conduit?] * link:#_typical_use_cases_client_role[Typical Use Cases - Client Role] * link:#_suite_characteristics[Suite Characteristics] * link:#_network_aspects[Network Aspects] * link:#_accessing_resources_from_a_remote_system_or_lan[Accessing Resources from a Remote System or LAN] ** link:#_illustrative_model[Illustrative Model] ** link:#_example_cli_access_across_the_internet_no_profile_used[Example CLI Access Across the Internet, No Profile Used] ** link:#_example_vpn_access_across_the_internet_preferred_profile_used_automatically[Example VPN Access Across the Internet, Preferred Profile Used Automatically] ** link:#_example_fs_access_within_a_lan_preferred_profile_bypassed_alternative_profile_selected_manually[Example FS Access Within a LAN, Preferred Profile Bypassed, Alternative Profile Selected Manually] ** link:#_example_vnc_access_within_a_lan_preferred_profile_bypassed_no_profile_used[Example VNC Access Within a LAN, Preferred Profile Bypassed, No Profile Used] *** link:#_vnc_utilities[VNC Utilities] * link:#_closing_an_access_session[Closing an Access Session] * link:#_providing_resources_to_a_remote_system[Providing Resources to a Remote System] *** link:#_enabling_vnc[Enabling VNC] * link:#_summary_of_files[Summary of Files] * link:#_references[References] {nbsp} {nbsp} [[under-toc]] == Conventions [icon="./images/icons/info.png"] [NOTE] This is additional information [icon="./images/icons/tip2.png"] [NOTE] This is a tip [icon="./images/icons/settings.png"] [NOTE] This is an example configuration or setting <> {nbsp} {nbsp} == What is SSH-Conduit? It is a suite of ways to privately make the resources of a system or a LAN available on another system. A system may concurrently perform two roles: * Access resources from a remote system or LAN * Provide resources from the local system or local LAN to a remote system Access to remote resources is available in the following ways: * CLI {nbsp} {nbsp} Open a terminal to a remote system * FS {nbsp} {nbsp} {nbsp} Add/remove a remote folder to/from a local system * VNC {nbsp} Operate the desktop of a remote system * VPN {nbsp} Join/leave a remote network Any or all of the above may be used at the same time and/or be provided from the local system to a remote system. You may use any of the suite components that access remote resources in two ways: * Make an ad hoc connection by manually inputting the information for each session * Create and save a profile that may be selected manually or automatically for a session It is anticipated the primary way of using a suite component will be via a profile. Each suite component may have multiple profiles. During launch, any or none of the profiles may be chosen before a connection is made. Any one of the profiles can optionally be designated as the preferred profile. In that case it is automatically loaded and connected at launch time. The systems contact each other across either the internet or local network. The connection is automatically encrypted to provide privacy during the session. The suite is self contained. Except for an ISP, connections across the internet do not depend upon the availability of third party services. Creation of external facilities or registration with their providers are not required. Additional financial commitment is not needed. <> {nbsp} {nbsp} == Typical Use Cases - Client Role === CLI **[black]#C#**ommand **[black]#L#**ine **[black]#I#**nterface mode is useful whenever any or all of these apply: + * You prefer to work by typing commands, + * The remote server system does not run a desktop GUI, + * You want to minimize the resources used by your local client system. + === FS **[black]#F#**ile **[black]#S#**ystem mode enables you to work with folders and files that are kept on a remote system. From your local laptop you create a secure encrypted connection to the remote system and automatically mount the remote folder tree into the local laptop folder tree. This makes the remote folders and files available to use in apps on your local laptop. You use them as if they are kept in your local laptop. === VNC **[black]#V#**irtual **[black]#N#**etwork **[black]#C#**omputing mode is useful whenever a remote system is running the suite VNC server and any or all of these apply: + * You prefer to work by clicking icons and buttons in a graphical desktop, + * You want to see the desktop of the remote system on the desktop of your local screen, + * You want to run apps using the CPU/RAM/storage of the remote system. + === VPN **[black]#V#**irtual **[black]#P#**rivate **[black]#N#**etwork mode is useful when you are concerned about browsing the web from an untrusted location such as an hotel. On your laptop in the hotel, you create a secure encrypted connection to your trusted LAN at your home. All your web browsing is then automatically conducted via your home LAN as if you were physically sitting at home. You browse the web privately with all traffic passing within the secure encrypted SSH tunnel. <> {nbsp} {nbsp} == Suite Characteristics Some common aspects apply in all cases: * The suite does not change any configuration of SSH you have implemented * The remote system that provides the resources must be running the SSH server daemon * To access remote resources, you must have an account on the remote system * An encrypted connection is established before the access session is granted * The access session does not require anyone to be present at the remote system * Launching an access session may be done with or without a profile that details how to connect * During the launch of an access session you may manually choose one of multiple profiles, or use one automatically * The automatic use of a preferred profile may be bypassed during launch All access sessions can connect via a LAN or the internet, except a VPN session which is via internet only When accessing remote resources across the internet: * The remote firewall/router must previously have been set up to forward a port to the system within the remote LAN on which the SSH server daemon is running * The forwarded port number may be any available number you choose to use [icon="./images/icons/info.png"] [NOTE] Each firewall/router handles port forwarding in its own way, this means there is no single description that can cover all variations. You should refer to the user manual to do the setting up. + [icon="./images/icons/tip2.png"] [TIP] If you are accessing remote resources across a local network rather than the internet, there is no need to forward a port from the firewall to the system on which SSH is running. In that case, both systems must be in the same local network i.e. behind the same LAN firewall/router. When providing resources from the local system or local LAN to a remote system: * An admin/info centre is available to report the status of, and enable limited management of, relevant services When in use the suite components: * Place very few demands on your system resources * Are suitable to run on both modern powerful kit and older less capable machines <> {nbsp} {nbsp} == Network Aspects The suite does not change any netwoking configuration you have set up. In the same way any other network based application, e.g. a web browser, needs networking to be operating normally, so does the suite. It relies on networking running in the usual way between the local and remote systems. The Network performance of a system can be influenced by any combination of, the vast range of potential kit, the huge variety of software that might be installed, the way applications are used, the enormous number of ISPs. This means there are some factors beyond the control of the suite. Constraining factors that might be present in either or both of the local and remote locations: * Capability and resources of either system e.g. ** Video adaptor and driver ** CPU power ** Amount of physical RAM ** Storage read/write speed ** Network adaptor speed * Reliability of connection to either network * Congestion of either network e.g. ** The number of concurrent network users ** The nature of the tasks the network users are conducting * Quality of service settings on either network Constraining factors that might be ISP dependent: * Speed of the modem making the connection to the ISP * Upload/Download speeds governed by the ISP * Congestion of the ISP network * Any other traffic shaping model imposed by the ISP <> {nbsp} {nbsp} == Accessing Resources from a Remote System or LAN The first time you connect to a remote system you will be asked whether to accept and store its key fingerprint. If you decline, the connection will not be established and the access session will not start. The range of ways in which the suite may be used mean it is impractical to try and cover every variation. The following examples illustrate some basic ways the suite can be used. You should adapt them to meet your particular circumstances or needs. === Illustrative Model The examples which follow below are based on this simplified model. It shows accessing remote resources within a LAN and also across the internet. In both cases: * Each of the systems providing the resources is running its own copy of the SSH server daemon * An encrypted tunnel is established and all traffic passes privately within it * For VNC access, each of the systems providing the resource is running its own copy of the suite VNC server * The IP address used in the examples is for illustration purposes only In the case where access is across the internet: * A port in the firewall/router is forwarded to the system within the LAN on which the SSH server daemon is running * The IP address and forwarded port number used in the examples are for illustration purposes only image:ssh-conduit/illustrative_model.jpg[] <> {nbsp} {nbsp} === Example CLI Access Across the Internet, No Profile Used In this example: * A profile for CLI access does not exist * You will manually input the connection details * When the remote system authorises the connection a termial window is opened to it {nbsp} image:ssh-conduit/cli_suite_menu.jpg[] From the suite main menu start CLI access mode {nbsp} image:ssh-conduit/cli_ad_hoc_window.jpg[] Input: * The external address of the remote firewall/router * The port number the remote firewall/router forwards to the remote system that is running the SSH server daemon * The user name on the remote system that will be used to log in to it When prompted input the password for the remote account. {nbsp} image:ssh-conduit/cli_terminal_to_remote_system.jpg[] A terminal to the remote system is automatically opened. + The user name and IP address is shown in the window title bar. <> {nbsp} {nbsp} === Example VPN Access Across the Internet, Preferred Profile Used Automatically In this example: * You will start and immediately stop VPN mode without making a connection to ensure a template profile exists * You will copy the template profile and edit it to contain the connection details * You will nominate the profile as the preferred profile * You will start VPN mode which without further input will automatically use the preferred profile * When the remote system authorises the connection an icon is added to the task bar {nbsp} image:ssh-conduit/vpn_suite_menu.jpg[] From the suite main menu start VPN access mode {nbsp} image:ssh-conduit/vpn_ad_hoc_window.jpg[] Immediately press the _Cancel_ button without inputting any details. + The suite automatically puts a template profile in place. {nbsp} Use your file manager to create a copy of the the template profile. + It is stored in a hidden file in your home folder _.config/ssh-conduit/sshuttle/profiles/ssh-conduit template profile.sshuttle_. + Give the copy a meaningful name e.g. _vpn to home lan as demo.sshuttle_. [icon="./images/icons/info.png"] [NOTE] sshuttle is the name of the application which SSH-Conduit uses for VPN connections Open _vpn to home lan as demo.sshuttle_ in your text editor and input the connection details. [icon="./images/icons/settings.png"] [NOTE] ==== Example vpn profile connection details ---- # The ip address to contact # This is usually the public ip address of the remote firewall # Example: IP_ADDRESS=xxx.xxx.xxx.xxx IP_ADDRESS=1.2.3.456 # Port number forwarded by the remote firewall to the remote ssh server system # Example: PORT_NUMBER=29346 PORT_NUMBER=34567 # Account name in the remote ssh server system that will be used to log in to it # Example: ACCOUNT_NAME=popeye ACCOUNT_NAME=demo # VPN mode # Choose only one of the following modes: # VPN_MODE=system-to-site # The remote network handles everything including web browsing and dns queries # This is equivalent to being physically present at the remote site # Typical use; connecting from an untrusted location to a trusted network # VPN_MODE=site-to-site # The local network handles everything including web browsing and dns queries # The remote network provides access to its resources # This is equivalent to a bridge between two discrete networks # Typical use; connecting a trusted network to another trusted network # VPN_MODE=manual # Define your own mode VPN_MODE=system-to-site ---- ==== For this example all other configuration values may safely be left empty. After entering and saving the details, your choices will be used whenever the profile is selected. {nbsp} The final step is to nominate the profile as the preferred profile so it is automatically used + In your text editor open the hidden file in your home folder _.config/ssh-conduit/sshuttle/sshuttle.conf_ + Input the name of your preferred profile [icon="./images/icons/settings.png"] [NOTE] ==== Example nominating a preferred vpn profile ---- # File name of the preferred profile to load # Spaces are allowed when the value is enclosed in quotes # Example: "ssh-conduit meaningful name.sshuttle" # Default: PREFERRED_PROFILE= PREFERRED_PROFILE="vpn to home lan as demo.sshuttle" ---- ==== For this example all other configuration values may safely be left unchanged. {nbsp} From the suite main menu start VPN access mode. + After a short countdown period a connection will be set up automatically. When prompted input the password for the remote account. {nbsp} To indicate a VPN connection, an icon is added to the task bar tray of your local system image:ssh-conduit/vpn_task_bar_icon.jpg[] <> {nbsp} {nbsp} === Example FS Access Within a LAN, Preferred Profile Bypassed, Alternative Profile Selected Manually In this example: * You must have multiple, fully configured profiles for FS access available from which you will make a selection * You must have previously nominated one of the available profiles as a preferred profile * You will bypass the automatic use of a preferred profile * You will manually browse for and use an alternative profile * When the remote system authorises the connection an icon is added to the task bar {nbsp} image:ssh-conduit/fs_suite_menu.jpg[] From the suite main menu start FS access mode {nbsp} image:ssh-conduit/fs_bypass_preferred_profile.jpg[] Press the _Ad Hoc_ button before the countdown ends [icon="./images/icons/tip2.png"] [TIP] If a button is not pressed, _Preferred_ is automatically started after a timeout + + The countdown period can be adjusted in _sshfs.conf_. + Each individual access component can be modified in a similar way by changing the value in its corresponding conf file. {nbsp} image:ssh-conduit/fs_choose_method_2.jpg[] Choose _Method 2_ and press the button showing a folder icon to select an existing profile [icon="./images/icons/info.png"] [NOTE] This option is disabled unless the template profile and at least one other profile are available. {nbsp} image:ssh-conduit/fs_select_alternative_profile.jpg[] Select the profile to use and press the _Open_ button [icon="./images/icons/info.png"] [NOTE] sshfs is the name of the application which SSH-Conduit uses for FS connections {nbsp} image:ssh-conduit/fs_selected_alternative_profile_shown_in_button.jpg[] The name of the selected alternative profile is shown in the button. + Press the _OK_ button to begin making the connection When prompted input the password for the remote account. {nbsp} To indicate an FS connection, an icon is added to the task bar tray of your local system image:ssh-conduit/fs_task_bar_icon.jpg[] <> {nbsp} {nbsp} === Example VNC Access Within a LAN, Preferred Profile Bypassed, No Profile Used In this example: * You must have at least one, fully configured profile for VNC access * You must have previously nominated a profile as a preferred profile * You will bypass the automatic use of a preferred profile * You will manually input the connection details * When the remote system authorises the connection a window will open showing the remote system screen on your local desktop {nbsp} image:ssh-conduit/vnc_suite_menu.jpg[] From the suite main menu start VNC access mode {nbsp} image:ssh-conduit/vnc_bypass_preferred_profile.jpg[] Press the _Ad Hoc_ button before the countdown ends [icon="./images/icons/tip2.png"] [TIP] If a button is not pressed, _Preferred_ is automatically started after a timeout + + The countdown period can be adjusted in _ssvnc.conf_. + Each individual access component can be modified in a similar way by changing the value in its corresponding conf file. {nbsp} image:ssh-conduit/vnc_ssvnc_input_window.jpg[] Input: * The user name on the remote system that will be used to log in to it * The LAN IP address of the remote system that is running the suite VNC server Press the _Connect_ button When prompted input two passwords: * One for the remote account login * One for the VNC server to open the session [icon="./images/icons/tip2.png"] [TIP] An alternative to being prompted for the VNC password is to input it in the _VNC Password_ field in the above window + + If the SSH VNC Viewer window is too small for comfortable use, increase the size of the font in _ssvnc.conf_. The window will adjust to accommodate the text size. [icon="./images/icons/info.png"] [NOTE] It is recommended you do not save the profile by pressing the _Save_ button. Doing so will create a profile that is different to the suite standard template. It will be more difficult for you to edit and may omit optimizations the standard template contains. The recommended way to create a profile is by copying ssh-conduit_template_profile.ssvnc, in a similar way to that described in an example above. {nbsp} image:ssh-conduit/vnc_remote_login_screen.jpg[] A window showing the remote system screen is automatically opened. [icon="./images/icons/info.png"] [NOTE] A VNC access session is able to display the remote system screen whether or not anyone is logged into the remote system. In this way, an increased security risk can be avoided. Instead of leaving the remote system in a state where a user is permanently logged in, it may be left at its log in screen. In such a case, a standard log in may be performed by a user physically present at the remote location, or one connecting over a network to hold a VNC access session. [icon="./images/icons/tip2.png"] [TIP] If the remote desktop is too large to fit within your local desktop, refer to the section _VNC Utilities_. + ==== VNC Utilities When the access session is granted and the desktop of the remote system is showing on your desktop, a range of built-in utilities become available. Move the your pointer into the shared desktop and press F8. + A popup menu is displayed. image:ssh-conduit/vnc_utilities_popup_window.jpg[] Select _Dismiss popup_ to close the popup menu. + Select _Quit viewer_ to end the session and the connection to the remote system. The remaining entries are described in the installed or on-line manual SSVNC. + Some provide enhanced functionality, others affect perceived performance. Some that might improve perceived performance * _8 Bit Color_ reduces the number of colors in the shared desktop displayed on your local screen * _Grey Scale_ displays only shades of grey in the shared desktop displayed on your local screen Some that will probably degrade perceived performance * _Full Color_ displays the maximum number of colors in the shared desktop displayed on your local screen * _Scale Viewer_ adjusts the size of the shared desktop displayed on your local screen * _Set 1/n Server Scale_ adjusts the size of the shared desktop displayed on your local screen * _Toggle Tight/ZRLE_ adjusts the way in which changes on the receiver desktop are handled on your local screen [icon="./images/icons/info.png"] [NOTE] Quality level, Compress level, and Disable JPEG only apply when using Tight encoding rather than the default ZRLE In addition to the popup menu tweaks, perceived performance might be improved by altering the screen resolution of the remote system. In the shared desktop, adjust screen resolution to a lower value. The lower the value the more noticable is the potential improvement. + This is also a good way to ensure the remote desktop fits entirely within your local desktop. + Before closing the VNC access session, reset the remote screen resolution to its original value via the shared desktop. [icon="./images/icons/tip2.png"] [TIP] Whatever performance tweaks are used, the amount by which performance changes will vary from system to system and network to network. <> {nbsp} {nbsp} == Closing an Access Session There are several ways to end an access session: . From the suite main menu, choose the access component you want to stop and press the _OK_ button. + One of two screens will be shown depending on whether a profile exists for the component. + From either screen you can disconnect and end the session. . You may left-click either of these icons whenever thay are showing in the system tray of the task bar. + image:ssh-conduit/fs_task_bar_icon.jpg[] image:ssh-conduit/vpn_task_bar_icon.jpg[] . A CLI session should be closed by typing the command _exit_ into its terminal window. . To end a VNC session, place your pointer arrow within the remote desktop window, press F8 on your keyboard and select _Quit viewer_. <> {nbsp} {nbsp} == Providing Resources to a Remote System Prerequisites on the system providing the resources: * SSH server daemon is running * A user account exists for each user requesting an access session Before access to a resource is granted: * A log-in request must be received via SSH from the system requesting an access session * The system providing the resource must authorise the log-in request After a successful log-in, the requested resource is made available automatically. === Enabling VNC Before providing VNC access, a few set up steps are required. These need to be done once only: * Create a VNC password the server will require to be supplied each time a remote system requests a VNC access session * Ensure the suite VNC server is available before and during every log-in and after every log-out * Show a VNC server icon in the task bar tray when the server is started automatically at boot-up and is currently running Both creating a VNC password and enabling the VNC server are done via menu items {nbsp} image:ssh-conduit/adm_suite_menu.jpg[] From the suite main menu start ADM administration mode {nbsp} image:ssh-conduit/adm_change_vnc_password.jpg[] {nbsp} [underline]#*VNC Password*# Before the server grants access to a session, the system requesting the access must supply a VNC password which the VNC server must authorise. This provides an additional layer of security and control over who is allowed to obtain a VNC access session. From the menu select _Change the password the VNC server requires to open a session_ * Input your local administrative password when prompted * Input the VNC password you want to set up * Confirm the VNC password [icon="./images/icons/tip2.png"] [TIP] The password can be changed at any time by repeating the above steps. {nbsp} [underline]#*VNC Server Availability*# Providing VNC is different to providing the other types of resources. It is the only type that requires its own server to be running. Although the amount of RAM used by the VNC server is tiny, in the interests of minimizing RAM usage it is installed in a deactivated state. The primary goal of the suite is to access resouces on an unattended remote system. To do that, the VNC server needs to be available both before and after a user has logged-in. By starting the server as part of the system boot-up routine it sets itself up in the required way. It is available before and during a log-in and automatically restarts after a log-out. From the menu select _Toggle auto start of the SSH-Conduit VNC Server for next boot up_ * A message will be displayed indicating whether the server will or will not be started during the next boot up * Reboot the system [icon="./images/icons/info.png"] [NOTE] To cover unusual circumstances, a menu option is available _Start the VNC server for the current log-in session only_ Because the server is not available before log-in or after log-out, the circumstances in which this mode is useful are quite limited. [icon="./images/icons/tip2.png"] [TIP] Only a single instance of the suite VNC server is permitted to run. {nbsp} [underline]#*VNC Server Icon in Task Bar Tray*# The icon is shown while the server is running: * It changes colour to indicate when an access session has been granted * It provides a menu of server management tasks * It is a way of opening the server GUI window It can only be displayed when a user is logged-in and their desktop is running. When the server is started during the system boot-up and the log-in screen is displayed awaiting a log-in, a user owned desktop is not yet started. In that case the GUI icon must be started separately when a user owned session begins. In your text editor open the file that controls the apps to run for your log-in session. Ensure the following entry is present. [icon="./images/icons/settings.png"] [NOTE] ==== Command to display an x11vnc GUI after a user log-in ---- ... # Uncomment to attach a gui to a running ssh-conduit-x11vnc server ssh-conduit-x11vnc.sh gui & ... ---- ==== [icon="./images/icons/tip2.png"] [TIP] The server window can be shown on the desktop instead of the tray icon. + Edit _supplementary.conf_ and change the appropriate value. + + If the server window or icon menu is too small for comfortable use, increase the size of the font in _supplementary.conf_. The window or icon menu will adjust to accommodate the text size. <> {nbsp} {nbsp} == Summary of Files {nbsp} [underline]#*Configuration and profile files:*# .... .config/ssh-conduit/ ├── cli │   ├── profiles │   │   └── ssh-conduit template profile.cli │   └── cli.conf ├── sshfs │   ├── profiles │   │   └── ssh-conduit template profile.sshfs │   └── sshfs.conf ├── sshuttle │   ├── profiles │   │   └── ssh-conduit template profile.sshuttle │   └── sshuttle.conf └── ssvnc ├── profiles -> /home/USERNAME/.vnc/profiles │   ├── ssh_known_hosts │   └── ssh-conduit_template_profile.ssvnc └── ssvnc.conf /etc/ssh-conduit/ └── x11vnc ├── supplementary.conf └── x11vncrc .... {nbsp} [underline]#*Executable files:*# .... /usr/local/bin/ ├── ssh-conduit-admin-centre.sh ├── ssh-conduit-cli.sh ├── ssh-conduit.sh ├── ssh-conduit-sshfs.sh ├── ssh-conduit-sshuttle.sh ├── ssh-conduit-ssvnc.sh └── ssh-conduit-x11vnc.sh /etc/init.d/ └── ssh-conduit-vnc-server .... {nbsp} [underline]#*Library files:*# .... /usr/local/lib/ssh-conduit/ ├── button-icons │   ├── Ad-Hoc-16.png │   ├── Cancel-16.png │   ├── Check-16.png │   ├── Close-16.png │   ├── Help-16.png │   ├── Network-Disconnected-16.png │   └── Target-16.png ├── tray-icons │   ├── ssh-conduit-f-48.png │   └── ssh-conduit-v-48.png └── lib-ssh-conduit-suite .... {nbsp} [underline]#*Log files:*# .... /var/log/ ├── ssh-conduit-x11vnc.log (x11vnc) └── syslog (sshuttle) .... <> {nbsp} {nbsp} == References {nbsp} [underline]#*VIDEO:*# https://www.youtube.com/watch?v=Y0up7Cluf4s + [underline]#*OPENSSH:*# https://www.openssh.com + [underline]#*SSHFS:*# https://github.com/libfuse/sshfs + [underline]#*SSHUTTLE:*# https://github.com/sshuttle/sshuttle + [underline]#*SSVNC:*# http://www.karlrunge.com/x11vnc/ssvnc.html + [underline]#*X11VNC:*# http://www.karlrunge.com/x11vnc <>