# sirup: simple IP rotation using python
[](https://github.com/ivory-tower-private-power/sirup/actions/workflows/build.yml)
[](https://sirup-vpn.readthedocs.io/en/latest/?badge=latest)
[](https://sonarcloud.io/dashboard?id=ivory-tower-private-power_sirup)
[](https://fair-software.eu)
[](https://zenodo.org/doi/10.5281/zenodo.10261948)
<!--
[](https://research-software-directory.org/software/sirup) -->
<!-- [](https://pypi.python.org/project/sirup/) -->
<!-- [](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>) -->
<!-- [](https://sonarcloud.io/dashboard?id=ivory-tower-private-power_sirup) -->
<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/cffconvert.yml) -->
<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/sonarcloud.yml) -->
<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/markdown-link-check.yml) -->
A wrapper around the openvpn CLI to connect to VPN servers and rotate the IP address in python programs.
## What is required
- An account with a VPN service that supports openvpn (for instance ProtonVPN or surfshark).
- A linux OS with superuser rights.
- `openvpn` for linux. See [here](https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareReposgit) for installation instructions.
## How to install
To install from pip, do:
```console
python -m pip install sirup
```
To install sirup from GitHub repository, do:
```console
python -m pip install 'sirup @ git+https://github.com/ivory-tower-private-power/sirup'
```
## How to use sirup
The package has two functionalities: connecting to a VPN server, and rotating the IP address.
**1. Start up**
This step is necessary for both functionalities.
```python
import os
import getpass
import time
seed = 123
mypass = "/path/to/credentials.txt" # the user name and password credentials from your user account with the VPN service
config_path = "/path/to/config/files/" # the .opvn configuration files from your VPN service
```
**Functionality 1: Connecting to a single VPN server**
The `sirup.VPNConnector.VPNConnector` class has two methods: `connect` and `disconnect`. They are used as follows.
```python
from sirup.VPNConnector import VPNConnector
config_file = os.path.join(config_path, "name-of-one-config-file.ovpn")
pwd = getpass.getpass()
connector = VPNConnector(auth_file=mypass, config_file=config_file)
connector.connect(pwd=pwd)
time.sleep(10)
connector.disconnect(pwd=pwd)
```
**Functionality 2: Using the IP rotation feature**
The `sirup.IPRotator.IPRotator` class has three methods: `connect()`, `rotate()`, `disconnect()`. They are used as follows.
```python
from sirup.IPRotator import IPRotator
rotator = IPRotator(auth_file=mypass, config_location=config_path, seed=seed) # will ask for the sudo password
rotator.connect()
print(rotator.connector.current_ip)
rotator.rotate()
print(rotator.connector.current_ip)
rotator.disconnect()
```
### Note
Before using the package, have a look at ["Making sure the VPN connection works correctly"](https://github.com/ivory-tower-private-power/sirup/blob/main/docs/correct_connection.rst) to make sure the VPN service works properly.
## Documentation
The documentation of sirup can be found on [Read the Docs](https://sirup-vpn.readthedocs.io/en/latest/).
## Contributing
If you want to contribute to the development of sirup,
have a look at the [contribution guidelines](docs/CONTRIBUTING.md).
## Credits
This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [NLeSC/python-template](https://github.com/NLeSC/python-template).
Raw data
{
"_id": null,
"home_page": "https://github.com/ivory-tower-private-power/sirup",
"name": "sirup",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ip-rotation, openvpn",
"author": "Flavio Hafner",
"author_email": "f.hafner@esciencecenter.nl",
"download_url": "https://files.pythonhosted.org/packages/67/e8/067c7a1eb8e04e5e14f03d3d8d9d884f74a025029e2d7c80b19e4dae27f9/sirup-0.2.3.tar.gz",
"platform": null,
"description": "# sirup: simple IP rotation using python\n\n[](https://github.com/ivory-tower-private-power/sirup/actions/workflows/build.yml)\n[](https://sirup-vpn.readthedocs.io/en/latest/?badge=latest)\n[](https://sonarcloud.io/dashboard?id=ivory-tower-private-power_sirup)\n[](https://fair-software.eu)\n[](https://zenodo.org/doi/10.5281/zenodo.10261948)\n<!-- \n[](https://research-software-directory.org/software/sirup) -->\n<!-- [](https://pypi.python.org/project/sirup/) -->\n\n<!-- [](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>) -->\n\n<!-- [](https://sonarcloud.io/dashboard?id=ivory-tower-private-power_sirup) -->\n\n<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/cffconvert.yml) -->\n<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/sonarcloud.yml) -->\n<!-- [](https://github.com/ivory-tower-private-power/sirup/actions/workflows/markdown-link-check.yml) -->\n\n\nA wrapper around the openvpn CLI to connect to VPN servers and rotate the IP address in python programs. \n\n\n\n## What is required\n- An account with a VPN service that supports openvpn (for instance ProtonVPN or surfshark).\n- A linux OS with superuser rights.\n- `openvpn` for linux. See [here](https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareReposgit) for installation instructions.\n\n\n## How to install\n\nTo install from pip, do:\n\n```console\npython -m pip install sirup\n```\n\nTo install sirup from GitHub repository, do:\n\n```console\npython -m pip install 'sirup @ git+https://github.com/ivory-tower-private-power/sirup'\n```\n\n## How to use sirup\n\nThe package has two functionalities: connecting to a VPN server, and rotating the IP address. \n\n**1. Start up**\n\nThis step is necessary for both functionalities.\n\n```python\nimport os \nimport getpass\nimport time \n\nseed = 123\nmypass = \"/path/to/credentials.txt\" # the user name and password credentials from your user account with the VPN service\nconfig_path = \"/path/to/config/files/\" # the .opvn configuration files from your VPN service\n```\n\n**Functionality 1: Connecting to a single VPN server**\n\nThe `sirup.VPNConnector.VPNConnector` class has two methods: `connect` and `disconnect`. They are used as follows.\n\n```python\nfrom sirup.VPNConnector import VPNConnector\n\nconfig_file = os.path.join(config_path, \"name-of-one-config-file.ovpn\")\npwd = getpass.getpass()\n\nconnector = VPNConnector(auth_file=mypass, config_file=config_file)\n\nconnector.connect(pwd=pwd)\n\ntime.sleep(10)\nconnector.disconnect(pwd=pwd)\n```\n\n**Functionality 2: Using the IP rotation feature**\n\nThe `sirup.IPRotator.IPRotator` class has three methods: `connect()`, `rotate()`, `disconnect()`. They are used as follows.\n\n```python\nfrom sirup.IPRotator import IPRotator\n\nrotator = IPRotator(auth_file=mypass, config_location=config_path, seed=seed) # will ask for the sudo password\n\nrotator.connect()\nprint(rotator.connector.current_ip)\n\nrotator.rotate()\nprint(rotator.connector.current_ip)\n\nrotator.disconnect()\n```\n\n### Note\n\nBefore using the package, have a look at [\"Making sure the VPN connection works correctly\"](https://github.com/ivory-tower-private-power/sirup/blob/main/docs/correct_connection.rst) to make sure the VPN service works properly.\n\n\n## Documentation\n\nThe documentation of sirup can be found on [Read the Docs](https://sirup-vpn.readthedocs.io/en/latest/).\n\n\n## Contributing\n\nIf you want to contribute to the development of sirup,\nhave a look at the [contribution guidelines](docs/CONTRIBUTING.md).\n\n## Credits\n\nThis package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [NLeSC/python-template](https://github.com/NLeSC/python-template).\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple IP rotation using python.",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/ivory-tower-private-power/sirup/issues",
"Homepage": "https://github.com/ivory-tower-private-power/sirup"
},
"split_keywords": [
"ip-rotation",
" openvpn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea0a25cc4084a1f8bf5e3b588981a91b5abb05976a55a01097e70c3a5ecd032d",
"md5": "f9ea5c97d31ae22acc6ebcd684753ae1",
"sha256": "a952887d72729f38dcd71eae177acc806016b4aa5c4784695accfb319634b692"
},
"downloads": -1,
"filename": "sirup-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9ea5c97d31ae22acc6ebcd684753ae1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16295,
"upload_time": "2024-03-21T10:26:48",
"upload_time_iso_8601": "2024-03-21T10:26:48.722761Z",
"url": "https://files.pythonhosted.org/packages/ea/0a/25cc4084a1f8bf5e3b588981a91b5abb05976a55a01097e70c3a5ecd032d/sirup-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "67e8067c7a1eb8e04e5e14f03d3d8d9d884f74a025029e2d7c80b19e4dae27f9",
"md5": "2c9742588b8765b52e52f2e9dc1e4a6a",
"sha256": "af796d9d40a0caa4ed7d2152729b5bb8116e2e4217c97faecc42fa374de6423d"
},
"downloads": -1,
"filename": "sirup-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "2c9742588b8765b52e52f2e9dc1e4a6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22416,
"upload_time": "2024-03-21T10:26:50",
"upload_time_iso_8601": "2024-03-21T10:26:50.407465Z",
"url": "https://files.pythonhosted.org/packages/67/e8/067c7a1eb8e04e5e14f03d3d8d9d884f74a025029e2d7c80b19e4dae27f9/sirup-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 10:26:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivory-tower-private-power",
"github_project": "sirup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sirup"
}
JSON
