2 Star 0 Fork 0

mirrors_SoftwareAG/cumulocity-remote-access-local-proxy

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

Deprecation Notice

This tool is not further developed, as it was fully replaced by a successor: go-c8y-cli

Check out the migration guide to migrate to go-c8y-cli: Migration Guide

Local Proxy for Cumulocity Cloud Remote Access

This 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.

architecture

The proxy is written in Python3.

Installation

Migration Notes

If you are upgrade from 1.x please see the MIGRATION to V2 NOTES as 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 the DEVELOPER notes for details.

Installation via pip (hosted in pypi)

pip install c8ylp

Note: Depending on your python setup, you may need to use pip3 instead of pip.

Installing a specific version

You can install specific version by specifying the version number when using pip.

pip install c8ylp==1.5.0

Or 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 Code

Clone the project, then navigate to the root folder of the project and run:

pip install .

Usage

Prerequisites & Limitations

Run c8ylp

c8ylp supports 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/-h option.

The command can be launched by either using the c8ylp binary or by calling the c8ylp module via python.

c8ylp

# or calling via python (or use python3)
python -m c8ylp

The available commands can be shown using:

% c8ylp --help
Usage: c8ylp [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  connect  Connect to a device via different protocols
  login    Login and save token to an environment file
  plugin   Run a custom plugin (installed under ~/.c8ylp/plugins/)
  server   Start local proxy in server mode
  version  Show the c8ylp version number

Common usages

The following scenarios show the common use cases of c8ylp.

Launching as local proxy server

c8ylp server <device> --env-file .env

The 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 session

If 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:

c8ylp connect ssh <device> --ssh-user <device_username> --env-file .env

Usage with a socket path

This is a unix only option

c8ylp server <device> --env-file .env --socket-path /tmp/device.socket

then connect with ssh like:

ssh -o 'ProxyCommand=socat - UNIX-CLIENT:/tmp/device.socket' <device_username>@localhost

Usage with stdin-/out forwarding

Using stdin/out forwarding to Cumulocity enables the use of c8ylp as 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 the c8ylp login --env-file .env command that will update the environment file. As long as the session is active the Cumulocity server can be used as proxy command with ssh as following:

ssh -o 'ProxyCommand=c8ylp server <device> --stdio --env-file .env' <device_username>@<device>

By adding the proxy command to the .ssh/config file, 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 typing ssh <device>. For this use the following example configuration (%n will be replaced by ssh with the given device name):

Host <device>
    User <device_username>
    PreferredAuthentications publickey
    IdentityFile <identify_file>
    ServerAliveInterval 120
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ProxyCommand c8ylp server %n --stdio --env-file .env

# Or you can create a generic ssh config for all devices with a similar prefix:
# Usage;
#   => ssh linux-device01
#   => ssh linux-device02
Host linux-*
    User admin
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/myprivatekey
    ServerAliveInterval 120
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ProxyCommand c8ylp server %n --stdio --env-file .env

Command documentation

The command usage and all options can be viewed online on the following pages:

Configuration

c8ylp can 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 file

Create a file called .env and add the following contents:

# Cumulocity settings
C8Y_HOST=<cumulocity_host>
C8Y_USER=<your_cumulocity_username>

# c8ylp settings
C8YLP_VERBOSE=true

Then reference the file from the command line:

c8ylp server test-device --env-file .env

You 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/zsh
export C8YLP_ENV_FILE=tenant1.config

# Now call c8ylp, and it will read the dotenv file "tenant1.config" automatically
c8ylp connect ssh my-device-name

The environment variables corresponding to each option can be viewed by using the in-built help for each command.

c8ylp server --help

c8ylp connect ssh --help

Please 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>&1

If 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 completion

c8ylp (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.

Note

Unfortunately tab completion is not supported in PowerShell or Cygwin.

# bash (profile: ~/.bashrc)
eval "$(_C8YLP_COMPLETE=bash_source c8ylp)"

# zsh (profile: ~/.zshrc)
eval "$(_C8YLP_COMPLETE=zsh_source c8ylp)"

# fish (profile: ~/.config/fish/config.fish)
_C8YLP_COMPLETE=fish_source c8ylp | source

Plugins

c8ylp can be extended in the form of plugins. Both python based plugins and bash scripts are supported. Checkout the plugins documentation 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 plugin c8ylp plugin command instead.

Plugins are loaded at runtime and can be listed by running the following command:

c8ylp plugin

Log

The log file can be found in the following directory.

~/.c8ylp/*.log

Where ~ 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 -v option 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/zsh
c8ylp [OPTIONS] > /dev/null 2>&1

Dependencies

The 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).

Contributing

Checkout the DEVELOPER Notes to 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 the Tech Community Forums.

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

暂无描述 展开 收起
README
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

不能加载更多了
马建仓 AI 助手
尝试更多
代码解读
代码找茬
代码优化
1
https://gitee.com/mirrors_SoftwareAG/cumulocity-remote-access-local-proxy.git
git@gitee.com:mirrors_SoftwareAG/cumulocity-remote-access-local-proxy.git
mirrors_SoftwareAG
cumulocity-remote-access-local-proxy
cumulocity-remote-access-local-proxy
main

搜索帮助