opensipscli 0.3.1__tar.gz → 0.4.0__tar.gz

opensipscli-0.4.0/.github/workflows/docker-push-image.yml

@@ -0,0 +1,26 @@
+name: Push OpenSIPS CLI Images in Docker Hub
+
+on:
+  push:
+  repository_dispatch:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Log in to Docker Hub
+      uses: docker/login-action@v2.1.0
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_TOKEN }}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v4
+      with:
+        context: ./docker/
+        push: true
+        tags: opensips/opensips-cli:latest

opensipscli-0.4.0/.github/workflows/docker-readme.yml

@@ -0,0 +1,26 @@
+---
+name: Update Docker Hub Description
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ./docker/docker.md
+      - .github/workflows/docker-readme.yml
+
+jobs:
+  dockerHubDescription:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+
+    - name: Docker Hub Description
+      uses: peter-evans/dockerhub-description@v4
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_TOKEN }}
+        repository: opensips/opensips-cli
+        readme-filepath: ./docker/docker.md
+        short-description: ${{ github.event.repository.description }}
+        enable-url-completion: true

opensipscli-0.4.0/.github/workflows/pypi.yml

@@ -0,0 +1,94 @@
+---
+name: Publish OpenSIPS CLI Python package to PyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python OpenSIPS CLI Python package to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/opensips-cli
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution OpenSIPS CLI to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the OpenSIPS CLI Python package with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'

opensipscli-0.4.0/.gitignore

@@ -0,0 +1,10 @@
+*.pyc
+*.pyo
+*.swp
+__pycach*
+/.pybuild/
+/build/
+/dist/
+/MANIFEST
+*egg-info/
+tags

{opensipscli-0.3.1/opensipscli.egg-info → opensipscli-0.4.0}/PKG-INFO

@@ -1,24 +1,23 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: opensipscli
-Version: 0.3.1
+Version: 0.4.0
 Summary: OpenSIPS Command Line Interface
-Home-page: https://github.com/OpenSIPS/opensips-cli
-Download-URL: https://github.com/OpenSIPS/opensips-cli/archive/master.zip
-Author: OpenSIPS Project
-Author-email: project@opensips.org
-Maintainer: Razvan Crainea
-Maintainer-email: razvan@opensips.org
-Project-URL: Source Code, https://github.com/OpenSIPS/opensips-cli
-Project-URL: Issues Tracker, https://github.com/OpenSIPS/opensips-cli/issues
-Classifier: Programming Language :: Python :: 3
+Project-URL: Homepage, https://github.com/OpenSIPS/opensips-cli
+Project-URL: Source, https://github.com/OpenSIPS/opensips-cli
+Project-URL: Issues, https://github.com/OpenSIPS/opensips-cli/issues
+Project-URL: Download, https://github.com/OpenSIPS/opensips-cli/archive/master.zip
+Author-email: OpenSIPS Project <project@opensips.org>
+Maintainer-email: Razvan Crainea <razvan@opensips.org>
+License: GNU General Public License v3 (GPLv3)
+License-File: LICENSE
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
-Description-Content-Type: text/markdown
-License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
 Requires-Dist: opensips
-Requires-Dist: mysqlclient<1.4.0rc1
-Requires-Dist: sqlalchemy<2,>=1.3.3
-Requires-Dist: sqlalchemy-utils
+Requires-Dist: pymysql
+Requires-Dist: sqlalchemy>=1.3.16
+Description-Content-Type: text/markdown
 
 # OpenSIPS CLI (Command Line Interface)
 
@@ -92,15 +91,15 @@ The OpenSIPSCLI object can receive a set of arguments/modifiers through the
 ```
 from opensipscli import args
 ...
-args = OpenSIPSCLIArgs(debug=True)
+args = args.OpenSIPSCLIArgs(debug=True)
 opensipscli = cli.OpenSIPSCLI(args)
 ...
 ```
 
-Custom settings can be provided thourgh the arguments, i.e.:
+Custom settings can be provided through the arguments, i.e.:
 ```
 # run commands over http
-args = OpenSIPSCLIArgs(communcation_type = "http",
+args = args.OpenSIPSCLIArgs(communication_type = "http",
                        url="http://127.0.0.1:8080/mi")
 ...
 ```
@@ -155,6 +154,9 @@ fifo used for the reply from OpenSIPS (Default: `/tmp`)
 (Default: `http://127.0.0.1:8888/mi`).
 * `datagram_ip`: The default IP used when `datagram` `communication_type` is used (Default: `127.0.0.1`)
 * `datagram_port`: The default port used when `datagram` `communication_type` is used (Default: `8080`)
+* `datagram_timeout`: Timeout for Datagram Socket.
+* `datagram_buffer_size`: Buffer size for Datagram Socket.
+* `datagram_unix_socket`: Unix Domain Socket to use instead of UDP.
 
 Each module can use each of the parameters above, but can also declare their
 own. You can find in each module's documentation page the parameters that they

{opensipscli-0.3.1 → opensipscli-0.4.0}/README.md

@@ -70,15 +70,15 @@ The OpenSIPSCLI object can receive a set of arguments/modifiers through the
 ```
 from opensipscli import args
 ...
-args = OpenSIPSCLIArgs(debug=True)
+args = args.OpenSIPSCLIArgs(debug=True)
 opensipscli = cli.OpenSIPSCLI(args)
 ...
 ```
 
-Custom settings can be provided thourgh the arguments, i.e.:
+Custom settings can be provided through the arguments, i.e.:
 ```
 # run commands over http
-args = OpenSIPSCLIArgs(communcation_type = "http",
+args = args.OpenSIPSCLIArgs(communication_type = "http",
                        url="http://127.0.0.1:8080/mi")
 ...
 ```
@@ -133,6 +133,9 @@ fifo used for the reply from OpenSIPS (Default: `/tmp`)
 (Default: `http://127.0.0.1:8888/mi`).
 * `datagram_ip`: The default IP used when `datagram` `communication_type` is used (Default: `127.0.0.1`)
 * `datagram_port`: The default port used when `datagram` `communication_type` is used (Default: `8080`)
+* `datagram_timeout`: Timeout for Datagram Socket.
+* `datagram_buffer_size`: Buffer size for Datagram Socket.
+* `datagram_unix_socket`: Unix Domain Socket to use instead of UDP.
 
 Each module can use each of the parameters above, but can also declare their
 own. You can find in each module's documentation page the parameters that they

opensipscli-0.4.0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+All available versions are eligible for security updates
+
+## Reporting a Vulnerability
+
+For any security/vulnerability issues you may discover, please send us a full report at security@opensips.org.

{opensipscli-0.3.1 → opensipscli-0.4.0}/bin/opensips-cli

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 from opensipscli import main
 

opensipscli-0.4.0/docker/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:slim-trixie
+LABEL maintainer="Razvan Crainea <razvan@opensips.org>"
+
+USER root
+
+# Set Environment Variables
+ENV DEBIAN_FRONTEND noninteractive
+
+#install basic components
+RUN apt-get -y update -qq && \
+    apt-get -y install git
+
+#add keyserver, repository
+RUN git clone https://github.com/OpenSIPS/opensips-cli.git /usr/src/opensips-cli && \
+    cd /usr/src/opensips-cli && \
+    python3 -m pip install . && \
+    cd / && rm -rf /usr/src/opensips-cli
+
+RUN apt-get purge -y git && \
+    apt-get autoremove -y && \
+    apt-get clean
+
+ADD "run.sh" "/run.sh"
+
+ENV PYTHONPATH /usr/lib/python3/dist-packages
+
+ENTRYPOINT ["/run.sh", "-o", "communication_type=http"]

opensipscli-0.4.0/docker/Makefile

@@ -0,0 +1,13 @@
+NAME ?= opensips-cli
+OPENSIPS_DOCKER_TAG ?= latest
+
+all: build start
+
+.PHONY: build start
+build:
+	docker build \
+		--tag="opensips/opensips-cli:$(OPENSIPS_DOCKER_TAG)" \
+		.
+
+start:
+	docker run -d --name $(NAME) opensips/opensips-cli:$(OPENSIPS_DOCKER_TAG)

opensipscli-0.4.0/docker/docker.md

@@ -0,0 +1,55 @@
+# OpenSIPS CLI Docker Image
+
+Docker recipe for running [OpenSIPS Command Line
+Interface](https://github.com/OpenSIPS/opensips-cli).
+
+## Building the image
+You can build the docker image by running:
+```
+make build
+```
+
+This command will build a docker image with OpenSIPS CLI master version taken from
+the git repository
+
+## Parameters
+
+The container receives parameters in the following format:
+```
+[-o KEY=VALUE]* CMD [PARAMS]*
+```
+
+Meaning of the parameters is as it follows:
+
+* `-o KEY=VALUE` - used to tune `opensips-cli` at runtime; these parameters
+will end up in opensips-cli config file, in the `default` section, as
+`KEY: VALUE` lines
+* `CMD` - the command used to run; if the `CMD` ends with `.sh` extension, it
+will be run as a bash script, if the `CMD` ends with `.py` extension, it is
+run as a python script, otherwise it is run as a `opensips-cli` command
+* `PARAMS` - optional additional parameters passed to `CMD`
+
+## Run
+
+To run a bash script, simply pass the connector followed by the bash script:
+```
+docker run -d --name opensips-cli opensips/opensips-cli:latest \
+		   -o url=http://8.8.8.8:8888/mi script.sh
+```
+
+Similarly, run a python script:
+```
+docker run -d --name opensips-cli opensips/opensips-cli:latest \
+		   -o url=http://8.8.8.8:8888/mi script.py
+```
+
+To run a single MI command, use:
+```
+docker run -d --name opensips-cli opensips/opensips-cli:latest \
+		   -o url=http://8.8.8.8:8888/mi -x mi ps
+```
+
+## DockerHub
+
+Docker images are available on
+[DockerHub](https://hub.docker.com/r/opensips/opensips-cli).

opensipscli-0.4.0/docker/run.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+OPTS=
+CMD=
+PARAMS=
+CFG=/etc/opensips-cli.cfg
+
+echo "[default]" > "$CFG"
+
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+	-o|--option)
+		shift
+		P=$(cut -d'=' -f1 <<<"$1")
+		V=$(cut -d'=' -f2- <<<"$1")
+		echo "$P: $V" >> "$CFG"
+		;;
+	*)
+		if [ -z "$CMD" ]; then
+			CMD="$1"
+		else
+			PARAMS="${PARAMS} ${1}"
+		fi
+		;;
+	esac
+	shift
+done
+
+if [[ $CMD == *.py ]]; then
+	TOOL=python3
+elif [[ $CMD == *.sh ]]; then
+	TOOL=bash
+else
+	TOOL=opensips-cli
+fi
+
+exec $TOOL $CMD $PARAMS

opensipscli-0.4.0/docs/INSTALLATION.md

@@ -0,0 +1,108 @@
+# Installation
+
+`opensips-cli` is the intended convenient command-line interface for
+administrating `opensips 3.x` installations.
+
+Since `version 3.x`, the former script tool `opensipsctl` has been removed.
+Its successor, `opensips-cli`, offers many advantages and will improve handling
+for regular tasks in a pleasant console environment.
+
+## From Packages
+
+### Debian packages (.deb)
+
+Add the ["cli-releases" repository from apt.opensips.org](https://apt.opensips.org/packages.php?v=cli)
+to your system using the instructions provided, then install the
+`opensips-cli` package.
+
+Supported Operating Systems (at the time of writing):
+
+* Debian 8-10
+* Ubuntu 14.04, 16.04, 18.04, 19.04
+
+### RPM packages (.rpm)
+
+The ["opensips-yum-releases" meta-package from yum.opensips.org](https://yum.opensips.org/)
+will install a repository that includes both `opensips` and `opensips-cli`
+packages.  Once installed, install the `opensips-cli` package.
+
+Supported Operating Systems (at the time of writing):
+
+* RHEL 6-8, CentOS 6-8, Scientific Linux 6-8, Oracle Linux 6-8
+* Fedora 27-31
+
+### Arch Linux AUR
+
+The distribution is managed as a rolling release.  Packages are administered
+via the `pacman` front-end.  Please install the `opensips-cli` package from the
+`AUR` using your favorite client:
+
+```
+# nightly build (latest `master` branch)
+yay opensips-cli-git
+
+# latest release branch
+yay opensips-cli
+```
+
+## From Source Code
+
+### Requirements
+
+Before building the CLI, you need to install some dependencies.  The process
+will vary on every supported operating system.
+
+#### Debian / Ubuntu
+
+```
+# required OS packages
+sudo apt install python3 python3-pip python3-pymysql python3-sqlalchemy \
+                 python3-openssl
+
+# alternatively, you can build the requirements from source
+sudo pip3 install PyMySQL sqlalchemy pyOpenSSL
+```
+
+#### Red Hat / CentOS
+
+```
+# required CentOS 7 packages
+sudo yum install python36 python36-pip python36-PyMySQL \
+                 python36-sqlalchemy python36-pyOpenSSL
+
+# required CentOS 8 packages
+sudo yum install python3 python3-pip python3-PyMySQL \
+                 python3-sqlalchemy python3-pyOpenSSL
+
+# alternatively, you can build the requirements from source
+sudo pip3 install PyMySQL sqlalchemy pyOpenSSL
+```
+
+### Download, Build & Install
+
+We can now download and install the latest development state from the GitHub
+repository:
+
+```
+git clone https://github.com/opensips/opensips-cli ~/src/opensips-cli
+cd ~/src/opensips-cli
+
+# local install (only visible to your user)
+python3 -m pip install --user .
+
+# system-wide install
+sudo python3 -m pip install .
+```
+
+### Cleaning up the install
+
+To clean up the manually built and installed `opensips-cli` package, run:
+
+```
+python3 -m pip uninstall opensipscli
+```
+
+## Database Installation
+
+Follow the [Database](modules/database.md#Examples) module documentation for a
+complete guide.

opensipscli-0.4.0/docs/modules/database.md

@@ -0,0 +1,144 @@
+# OpenSIPS CLI - Database module
+
+Module used to manipulate the database used by OpenSIPS.
+
+## Commands
+
+This module exports the following commands:
+* `create` - creates a new database. Can receive an optional parameter,
+specifying the name of the database to be created. This command also deploys
+the standard OpenSIPS table, as well as other standard tables
+* `drop` - drops a database. Can receive an optional parameter, specifying
+which database to delete.
+* `add` - adds a new module's tables in an existing database. Receives as
+parameter the name of the module, as specified in the OpenSIPS scripts
+hierarchy.
+* `migrate` - copy and convert an OpenSIPS database into its next OpenSIPS
+release equivalent
+
+## Configuration
+
+### Database Schema Files
+
+The database schema files for each supported SQL backend can be installed via
+their corresponding OpenSIPS client module package.  For example (only install modules useful to you):
+
+```
+apt install opensips-mysql-module opensips-postgres-module opensips-sqlite-module opensips-berkeley-module
+yum install opensips-mysql-module opensips-postgres-module opensips-sqlite-module opensips-berkeley-module
+```
+
+Once installed, the schema files will be auto-detected by `opensips-cli`.
+
+### Setting up the `database` module
+
+The following parameters are allowed in the config file:
+
+* `database_schema_path` (optional) - absolute path to the OpenSIPS DB schema directory,
+usually `/usr/share/opensips` if installed from packages or `/path/to/opensips/scripts` if you
+are using the OpenSIPS source tree.  Default: `/usr/share/opensips`
+* `database_admin_url` (optional) - a connection string to the database with privileged
+(administrator) access level which will be used to create/drop databases, as
+well as to create or ensure access for the non-privileged DB access user
+provided via `database_url`.  The URL combines schema, username, password, host
+and port.  Default: `mysql://root@localhost`.
+* `database_url` (optional) - the connection string to the database.  A good practice
+would be to use a non-administrator access user for this URL.  Default:
+`mysql://opensips:opensipsrw@localhost`.
+* `database_name` (optional) - the name of the database.  Modules may be separately added
+to this database if you choose not to install all of them.  Default: `opensips`.
+* `database_modules` (optional) - accepts the `ALL` keyword that indicates all the
+available modules should be installed, or a space-separated list of modules
+names.  If processed with the `create` command, the corresponding tables will
+be deployed.  Default: `acc alias_db auth_db avpops clusterer dialog
+dialplan dispatcher domain drouting group load_balancer msilo permissions
+rtpproxy rtpengine speeddial tls_mgm usrloc`.
+* `database_force_drop` (optional) - indicates whether the `drop` command will drop the
+database without user interaction.  Default: `false`
+
+## Usage Examples
+
+### Database Management
+
+Consider the following configuration file:
+
+```
+[default]
+#database_modules: acc clusterer dialog dialplan dispatcher domain rtpproxy usrloc
+database_modules: ALL
+
+#database_admin_url: postgresql://root@localhost
+database_admin_url: mysql://root@localhost
+```
+
+The following command will create the `opensips` database and all possible
+tables within the MySQL instance.  Additionally, the `opensips:opensipsrw` user
+will be created will `ALL PRIVILEGES` for the `opensips` database.  For some
+backends, such as PostgreSQL, any additionally required permissions will be
+transparently granted to the `opensips` user, for example: table-level or
+sequence-level permissions.
+
+```
+opensips-cli -x database create
+Password for admin DB user (root): _
+```
+
+If we want to add a new module, say `rtpproxy`, we have to run:
+
+```
+opensips-cli -x database add rtpproxy
+```
+The command above will create the `rtpproxy_sockets` table.
+
+A drop command will prompt the user whether they really want to drop the
+database or not:
+
+```
+$ opensips-cli -x database drop
+Do you really want to drop the 'opensips' database [Y/n] (Default is n): n
+```
+
+But setting the `database_force_drop` parameter will drop it without asking:
+```
+opensips-cli -o database_force_drop=true -x database drop
+```
+
+### Database Migration (MySQL only)
+
+The `database migrate` command can be used to _incrementally_ upgrade
+your OpenSIPS database.
+
+#### Migrating from 2.4 to 3.0
+
+```
+# fetch the 3.0 OpenSIPS repo & migration scripts
+git clone https://github.com/OpenSIPS/opensips -b 3.0 ~/src/opensips-3.0
+
+# provide the custom path to the migration scripts and perform the migration
+opensips-cli -o database_schema_path=~/src/opensips-3.0/scripts \
+             -x database migrate 2.4_to_3.0 opensips_2_4 opensips_mig_3_0
+```
+
+#### Migrating from 3.0 to 3.1
+
+```
+# fetch the 3.1 OpenSIPS repo & migration scripts
+git clone https://github.com/OpenSIPS/opensips -b 3.1 ~/src/opensips-3.1
+
+# provide the custom path to the migration scripts and perform the migration
+opensips-cli -o database_schema_path=~/src/opensips-3.1/scripts \
+             -x database migrate 3.0_to_3.1 opensips_3_0 opensips_mig_3_1
+```
+
+## Dependencies
+
+* [sqlalchemy](https://www.sqlalchemy.org/) - used to abstract the SQL
+database regardless of the backend used
+* [PyMySQL](https://github.com/PyMySQL/PyMySQL) - pure-Python MySQL/MariaDB
+driver used by SQLAlchemy when connecting to MySQL backends
+
+## Limitations
+
+This module can only manipulate database backends that are supported by the
+[SQLAlchemy](https://www.sqlalchemy.org/) project, such as  SQLite,
+Postgresql, MySQL, Oracle, MS-SQL.