Package: c8ylp
Local Proxy for Cumulocity Cloud Remote AccessThis is a proxy implementation for the Cloud Remote Access feature of Cumulocity which allows to connect to devices using native TCP-based clients like ssh, vnc, rdp etc.Main purpose of this proxy is to bridge all TCP packets via WebSocket. The local proxy is designed to run on clients where the native client software is installed.The proxy is written in Python3.InstallationMigration NotesIf your are upgrade from 1.x please see theMIGRATION to V2 NOTESas there are some breaking changes. Please forgive us, but you can be sure it is worth it! Version 2.x brings a lot of great features like interactive ssh sessions and plugins to make c8ylp even more useful!The Local Proxy can be installed via pip, or manually installed from the repository by cloning it.Additionally a Debian package (.deb) can be created by building the project yourself and hosting the package in your own Debian repository. See theDEVELOPER notesfor details.Installation via pip (hosted in pypi)pip install c8ylpNote: Depending on your python setup, you may need to usepip3instead ofpip.Installing a specific versionYou can install specific version by specifying the version number when using pip.pip install c8ylp==1.5.0Or if you want to install the latest v1.x version and do not want to upgrade to v2.x until you are ready, then use:pip install "c8ylp<2.0.0"Installation from Source CodeClone the project, then navigate to the root folder of the project and run:pip install .UsagePrerequisites & LimitationsPASSTHROUGH endpoint:To use the local proxy you need a remote access PASSTHROUGH endpoint configured on each of your devices you want to connect to. See this guide for further details:https://tech.forums.softwareag.com/t/how-to-get-started-with-cloud-remote-access-for-cumulocity-iot/258446#step-by-step-guide-to-setup-a-passthrough-connection-16Tenant Authentication Method:The desired tenant must be configured to use theOAI SecureAuthentication. Read more:https://cumulocity.com/guides/users-guide/administration/#authenticationSingle Device Tunnel only: The Local Proxy needs to be executed for each device tunnel you want to establish. Multiple device tunnels per single Local Proxy Instance is currently not supported due to the limitation of the SSH Protocol.Run c8ylpc8ylpsupports different commands depending on your use case. The commands are organized in a multi-level command structure. The list of available commands and subcommands can be shown by using the--help/-hoption.The command can be launched by either using thec8ylpbinary or by calling thec8ylpmodule via python.c8ylp# or calling via python (or use python3)python-mc8ylpThe available commands can be shown using:%c8ylp--helpUsage: c8ylp [OPTIONS] COMMAND [ARGS]...Options:--help  Show this message and exit.Commands:connect  Connect to a device via different protocolslogin    Login and save token to an environment fileplugin   Run a custom plugin (installed under ~/.c8ylp/plugins/)server   Start local proxy in server modeversion  Show the c8ylp version numberCommon usagesThe following scenarios show the common use cases ofc8ylp.Launching as local proxy serverc8ylpserver<device>--env-file.envThe port information will be shown in the terminal so that you can connect to it via a client corresponding to the protocol currently being used on the device (i.e. ssh, vnc etc.)Launching as local proxy server then launching an interactive ssh sessionIf you just want to connect via ssh using a once-off proxy instance using a random port number (to prevent conflicts with other applications), then use:c8ylpconnectssh<device>--ssh-user<device_username>--env-file.envUsage with a socket pathThis is a unix only optionc8ylpserver<device>--env-file.env--socket-path/tmp/device.socketthen connect with ssh like:ssh-o'ProxyCommand=socat - UNIX-CLIENT:/tmp/device.socket'<device_username>@localhostUsage with stdin-/out forwardingUsing stdin/out forwarding to Cumulocity enables the use ofc8ylpas a proxy command without the need of a local TCP server.
As proxy commands cannot interact with the user you have to ensure there is an active Cumulocity session.The session can be ensured by using thec8ylp login --env-file .envcommand that will update the environment file.
As long as the session is active the Cumulocity server can be used as proxy command withsshas following:ssh-o'ProxyCommand=c8ylp server <device> --stdio --env-file .env'<device_username>@<device>By adding the proxy command to the.ssh/configfile, the usage of the Cumulocity server can be simplified even more.
The file allows to define user and environment file so the connection can be done by simply typingssh <device>.
For this use the following example configuration (%nwill be replaced bysshwith the given device name):Host <device>User <device_username>PreferredAuthentications publickeyIdentityFile <identify_file>ServerAliveInterval 120StrictHostKeyChecking noUserKnownHostsFile /dev/nullProxyCommand c8ylp server %n --stdio --env-file .env#Oryoucancreateagenericsshconfigforalldeviceswithasimilarprefix:#Usage;#=>sshlinux-device01#=>sshlinux-device02Host linux-*User adminPreferredAuthentications publickeyIdentityFile ~/.ssh/myprivatekeyServerAliveInterval 120StrictHostKeyChecking noUserKnownHostsFile /dev/nullProxyCommand c8ylp server %n --stdio --env-file .envCommand documentationThe command usage and all options can be viewed online on the following pages:c8ylpc8ylp loginc8ylp serverc8ylp connectc8ylp connect sshc8ylp pluginc8ylp plugin commandc8ylp versionConfigurationc8ylpcan be configured via command line options or environment variables. The environment variables can either be set via the shell, or by using a dotenv file (i.e..env). When using a dotenv (environment) file then it needs to be provide to the--env-file <file>option.Example Usage: dotenv fileCreate a file called.envand add the following contents:# Cumulocity settingsC8Y_HOST=<cumulocity_host>C8Y_USER=<your_cumulocity_username># c8ylp settingsC8YLP_VERBOSE=trueThen reference the file from the command line:c8ylp server test-device --env-file .envYou can also set the path the dotenv file via an environment variable to save you adding it to all your commands manually. i.e.:# bash/zshexportC8YLP_ENV_FILE=tenant1.config# Now call c8ylp, and it will read the dotenv file "tenant1.config" automaticallyc8ylpconnectsshmy-device-nameThe environment variables corresponding to each option can be viewed by using the in-built help for each command.c8ylpserver--help

c8ylpconnectssh--helpPlease note that the Local Proxy will block the current terminal session. If you want to use it in background just use "&" and/or "nohup". As the relevant information will be stored in a log file as well you can forward the output to dev/null or to syslog if you want to do so.c8ylp server [options] > /dev/null 2>&1If no TCP Client is connected but Web Socket Connection is open it might get be terminated by a server timeout. The Local Proxy will automatically reestablish the connection in this case.If a TCP Client has been connected and the Web Socket Connection gets terminated, the TCP Client Connection will be terminated which results in that the Local Proxy terminates and needs to be restarted manually.Tab completionc8ylp(version >= 2.0.0) supports tab completion for bash, zsh and fish shells.To add/activate the completions you will need to add the corresponding line to your shell profile, and reload your shell afterwards.NoteUnfortunately tab completion is not supported in PowerShell or Cygwin.# bash (profile: ~/.bashrc)eval"$(_C8YLP_COMPLETE=bash_sourcec8ylp)"# zsh (profile: ~/.zshrc)eval"$(_C8YLP_COMPLETE=zsh_sourcec8ylp)"# fish (profile: ~/.config/fish/config.fish)_C8YLP_COMPLETE=fish_sourcec8ylp|sourcePluginsc8ylpcan be extended in the form of plugins. Both python based plugins and bash scripts are supported. Checkout thepluginsdocumentation for more information about how to create your own plugin, but it is intended for advanced users only. For simple one liners have a look at using the in-built generic pluginc8ylp plugin commandinstead.Plugins are loaded at runtime and can be listed by running the following command:c8ylp pluginLogThe log file can be found in the following directory.~/.c8ylp/*.logWhere~is your user folder.To increase the detail of log use the option--verbose or -v. If set, the log will be written on debug level.Log information will not be printed out to the console by default unless the--verbose or -voption is used. The log file however is always active to help provide a record of activities and to help diagnose any problems should they arise.You can suppress all console message (i.e. stdout) by redirecting the output to/dev/null.# bash/zshc8ylp[OPTIONS]>/dev/null2>&1DependenciesThe Local Proxy depends on the following components packages. The dependencies will be automatically installed when installing via pip or if you are installing c8ylp via a manually built Debian package (.deb).certificlickrequestssetuptoolswebsocket_clientContributingCheckout theDEVELOPER Notesto see how to contribute to the project.These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.For more information you can Ask a Question in theTech Community Forums.