# remoterunlib
`remoterunlib` is a Python library that facilitates remote command execution, Python function invocation, and PowerShell command execution over SSH. It is built on top of the Paramiko library and provides a simple interface for managing SSH connections and running commands or functions on remote machines.
## OpenSSH setup
Windows : [openssh_install](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=powershell)
## Features
- **SSH Connection Management**: Easily manage SSH connections with support for password and key-based authentication.
- **Remote Command Execution**: Run shell commands on remote machines.
- **Remote Python Function Invocation**: Serialize and execute Python functions remotely.
- **PowerShell Command Execution**: Execute PowerShell commands on remote Windows machines.
- **Remote machine Restart**: Restart the remote machine
## Installation
Install the package using pip:
```sh
pip install remoterunlib
```
## Usage
### Basic Usage
#### Initializing the SSH Client
```python
from remoterunlib import SSHClient
# Initialize the SSH client
client = SSHClient(hostname='remote_host', port=22, username='user', password='password')
client.login()
```
#### Running Shell Commands
```python
# Run a shell command
output, errors = client.run_command('ls -la', verbose=True) # if verbose False won't display live output in console
if output:
print("Shell Output:")
print(output)
if errors:
print("Shell Errors:")
print(errors)
```
#### Running Python Functions Remotely
```python
# Run the Python file remotely
# Will copy to Remote machine (#default path: C:\temp)
ssh_client.run_python_file("demo/selenium_test_script.py")
```
#### Running PowerShell Commands
```python
# Run a PowerShell command
ps_output, ps_errors = client.run_powershell_command('Get-Process', verbose=True) # if verbose False won't display live output in console
if ps_output:
print("PowerShell Output:")
print(ps_output)
if ps_errors:
print("PowerShell Errors:")
print(ps_errors)
```
#### ping machine
```python
# ping the remote machine
ssh_client.ping() # returns True if no errors occured
```
#### Reboot machine
```python
# Reboot remote machine and wait until wake up based on timeout
ssh_client.reboot(wait_until=300) # wait until 300 seconds
```
#### Closing the SSH Connection
```python
# Close the SSH connection
client.close()
```
### Advanced Usage
#### Using Key-based Authentication
```python
client = SSHClient(hostname='remote_host', port=22, username='user', key_file='/path/to/private_key')
client.login()
```
#### Handling Timeouts and Live Output
The `run_command` method supports a timeout parameter and displays live output. If a command exceeds the timeout, it will be terminated, and a timeout message will be displayed.
```python
output, errors = client.run_command('some_long_running_command', timeout=10)
```
#### Singleton Pattern
`SSHClient` uses the singleton pattern, ensuring that only one instance per hostname is created. If you attempt to create another instance with the same hostname, the existing instance will be returned.
```python
client1 = SSHClient(hostname='remote_host', port=22, username='user', password='password')
client2 = SSHClient(hostname='remote_host', port=22, username='user', password='password')
# client1 and client2 are the same instance
assert client1 is client2
```
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue on GitHub.
## License
This project is licensed under the MIT License. See the LICENSE file for more details.
## Acknowledgments
`remoterunlib` is built on top of [Paramiko](https://www.paramiko.org/). We thank the Paramiko team and contributors for their excellent work.
## Disclaimer
Running remote commands and executing functions on remote machines can pose security risks. Ensure that you only connect to trusted servers and that your use of this library complies with your organization's security policies.
Raw data
{
"_id": null,
"home_page": "https://github.com/dsharathrao/remoterunlib",
"name": "remoterunlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Sharath Kumar",
"author_email": "dsharathrao@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/aa/5463dc246775bce74c5c82d6e649990b46c8f693c67ad4b14400def46ddf/remoterunlib-0.1.6.tar.gz",
"platform": null,
"description": "\n# remoterunlib\n\n`remoterunlib` is a Python library that facilitates remote command execution, Python function invocation, and PowerShell command execution over SSH. It is built on top of the Paramiko library and provides a simple interface for managing SSH connections and running commands or functions on remote machines.\n\n## OpenSSH setup\n\nWindows : [openssh_install](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=powershell)\n\n## Features\n\n- **SSH Connection Management**: Easily manage SSH connections with support for password and key-based authentication.\n- **Remote Command Execution**: Run shell commands on remote machines.\n- **Remote Python Function Invocation**: Serialize and execute Python functions remotely.\n- **PowerShell Command Execution**: Execute PowerShell commands on remote Windows machines.\n- **Remote machine Restart**: Restart the remote machine\n## Installation\n\nInstall the package using pip:\n\n```sh\npip install remoterunlib\n```\n\n## Usage\n\n### Basic Usage\n\n#### Initializing the SSH Client\n\n```python\nfrom remoterunlib import SSHClient\n\n# Initialize the SSH client\nclient = SSHClient(hostname='remote_host', port=22, username='user', password='password')\nclient.login()\n```\n\n#### Running Shell Commands\n\n```python\n# Run a shell command\noutput, errors = client.run_command('ls -la', verbose=True) # if verbose False won't display live output in console\nif output:\n print(\"Shell Output:\")\n print(output)\nif errors:\n print(\"Shell Errors:\")\n print(errors)\n```\n\n#### Running Python Functions Remotely\n\n```python\n\n# Run the Python file remotely\n# Will copy to Remote machine (#default path: C:\\temp)\nssh_client.run_python_file(\"demo/selenium_test_script.py\")\n```\n\n#### Running PowerShell Commands\n\n```python\n# Run a PowerShell command\nps_output, ps_errors = client.run_powershell_command('Get-Process', verbose=True) # if verbose False won't display live output in console\nif ps_output:\n print(\"PowerShell Output:\")\n print(ps_output)\nif ps_errors:\n print(\"PowerShell Errors:\")\n print(ps_errors)\n```\n\n#### ping machine\n\n```python\n# ping the remote machine\nssh_client.ping() # returns True if no errors occured\n```\n\n#### Reboot machine\n\n```python\n# Reboot remote machine and wait until wake up based on timeout\nssh_client.reboot(wait_until=300) # wait until 300 seconds\n```\n\n#### Closing the SSH Connection\n\n```python\n# Close the SSH connection\nclient.close()\n```\n\n### Advanced Usage\n\n#### Using Key-based Authentication\n\n```python\nclient = SSHClient(hostname='remote_host', port=22, username='user', key_file='/path/to/private_key')\nclient.login()\n```\n\n#### Handling Timeouts and Live Output\n\nThe `run_command` method supports a timeout parameter and displays live output. If a command exceeds the timeout, it will be terminated, and a timeout message will be displayed.\n\n```python\noutput, errors = client.run_command('some_long_running_command', timeout=10)\n```\n\n#### Singleton Pattern\n\n`SSHClient` uses the singleton pattern, ensuring that only one instance per hostname is created. If you attempt to create another instance with the same hostname, the existing instance will be returned.\n\n```python\nclient1 = SSHClient(hostname='remote_host', port=22, username='user', password='password')\nclient2 = SSHClient(hostname='remote_host', port=22, username='user', password='password')\n\n# client1 and client2 are the same instance\nassert client1 is client2\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request or open an issue on GitHub.\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for more details.\n\n## Acknowledgments\n\n`remoterunlib` is built on top of [Paramiko](https://www.paramiko.org/). We thank the Paramiko team and contributors for their excellent work.\n\n## Disclaimer\n\nRunning remote commands and executing functions on remote machines can pose security risks. Ensure that you only connect to trusted servers and that your use of this library complies with your organization's security policies.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "remoterunlib is a Python library that facilitates remote command execution",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/dsharathrao/remoterunlib/issues",
"Homepage": "https://github.com/dsharathrao/remoterunlib",
"Repository": "https://github.com/dsharathrao/remoterunlib"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f11d10498e77b3ae3eee6abfec937497691146b4ecc3508cdbf42c53138c6847",
"md5": "7c6dacf3ead0b1d0fe05a58d14c7bca7",
"sha256": "5a2f86a070bd18b466578a60f6355350e8fb3f4989bca11a84e376f055fc18f1"
},
"downloads": -1,
"filename": "remoterunlib-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c6dacf3ead0b1d0fe05a58d14c7bca7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7150,
"upload_time": "2024-08-07T00:57:15",
"upload_time_iso_8601": "2024-08-07T00:57:15.282764Z",
"url": "https://files.pythonhosted.org/packages/f1/1d/10498e77b3ae3eee6abfec937497691146b4ecc3508cdbf42c53138c6847/remoterunlib-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6aa5463dc246775bce74c5c82d6e649990b46c8f693c67ad4b14400def46ddf",
"md5": "64918bbea99159c61263acd0ea530ff3",
"sha256": "17d06937520dae48258d4ede629cc2bc7de3db1d2431296604f26d23cef1514c"
},
"downloads": -1,
"filename": "remoterunlib-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "64918bbea99159c61263acd0ea530ff3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6362,
"upload_time": "2024-08-07T00:57:16",
"upload_time_iso_8601": "2024-08-07T00:57:16.551210Z",
"url": "https://files.pythonhosted.org/packages/e6/aa/5463dc246775bce74c5c82d6e649990b46c8f693c67ad4b14400def46ddf/remoterunlib-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-07 00:57:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dsharathrao",
"github_project": "remoterunlib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "remoterunlib"
}
JSON
