opensipscli 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -0,0 +1,38 @@
+name: Push OpenSIPS CLI Images in Docker Hub
+
+on:
+  push:
+  repository_dispatch:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v4
+
+    - name: Log in to Docker Hub
+      uses: docker/login-action@v4
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_TOKEN }}
+
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v4
+      with:
+        registry: ghcr.io
+        username: ${{ github.repository_owner }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v7
+      with:
+        context: ./docker/
+        push: true
+        tags: |
+          opensips/opensips-cli:latest
+          ghcr.io/opensips/opensips-cli:latest

{opensipscli-0.4.0 → opensipscli-0.4.2}/.github/workflows/docker-readme.yml

@@ -12,11 +12,11 @@ jobs:
   dockerHubDescription:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
 
     - name: Docker Hub Description
-      uses: peter-evans/dockerhub-description@v4
+      uses: peter-evans/dockerhub-description@v5
       with:
         username: ${{ secrets.DOCKER_USERNAME }}
         password: ${{ secrets.DOCKER_TOKEN }}

{opensipscli-0.4.0 → opensipscli-0.4.2}/.github/workflows/pypi.yml

@@ -9,9 +9,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -23,7 +23,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: python-package-distributions
         path: dist/
@@ -43,7 +43,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: python-package-distributions
         path: dist/
@@ -64,12 +64,12 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      uses: sigstore/gh-action-sigstore-python@v3.5.0
       with:
         inputs: >-
           ./dist/*.tar.gz

{opensipscli-0.4.0 → opensipscli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: opensipscli
-Version: 0.4.0
+Version: 0.4.2
 Summary: OpenSIPS Command Line Interface
 Project-URL: Homepage, https://github.com/OpenSIPS/opensips-cli
 Project-URL: Source, https://github.com/OpenSIPS/opensips-cli
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.8
 Requires-Dist: opensips
 Requires-Dist: pymysql
-Requires-Dist: sqlalchemy>=1.3.16
+Requires-Dist: sqlalchemy>=1.3.2
 Description-Content-Type: text/markdown
 
 # OpenSIPS CLI (Command Line Interface)

{opensipscli-0.4.0 → opensipscli-0.4.2}/docs/INSTALLATION.md

@@ -17,8 +17,8 @@ to your system using the instructions provided, then install the
 
 Supported Operating Systems (at the time of writing):
 
-* Debian 8-10
-* Ubuntu 14.04, 16.04, 18.04, 19.04
+* Debian 10-12
+* Ubuntu 18.04, 20.04, 22.04, 24.04
 
 ### RPM packages (.rpm)
 

{opensipscli-0.4.0 → opensipscli-0.4.2}/docs/modules/database.md

@@ -14,7 +14,10 @@ which database to delete.
 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
+  release equivalent
+* `pi` - creates a `pi_http` framework from the framework shipped with
+  OpenSIPS, using the configured database URL and modules. An optional output
+  path may be provided.
 
 ## Configuration
 
@@ -90,6 +93,17 @@ opensips-cli -x database add rtpproxy
 ```
 The command above will create the `rtpproxy_sockets` table.
 
+To create a provisioning framework for the configured modules, run:
+
+```
+opensips-cli -x database pi /etc/opensips/pi_framework.xml
+```
+
+The command reuses the framework shipped in the OpenSIPS `pi_http` scripts,
+including its module-specific columns, validations, and commands. When
+`database_modules` is not `ALL`, entries for other modules are removed from
+the generated file.
+
 A drop command will prompt the user whether they really want to drop the
 database or not:
 

{opensipscli-0.4.0 → opensipscli-0.4.2}/docs/modules/mi.md

@@ -7,9 +7,14 @@ commands and display the result in the console.
 
 This module exports all the commands that are exported by the OpenSIPS
 instance that `opensips-cli` points to. It fetches the available commands by
-running the OpenSIPS MI `which` command. When running a command, it returns
+running the OpenSIPS MI `which` command. It also loads MI aliases using the
+`which_aliases` command. When running a command, it returns
 the raw, unprocessed data from OpenSIPS.
 
+Aliases are accepted when executing commands, but are not included in command
+completion suggestions. Ambiguous aliases are ignored and must be invoked by
+their canonical command name.
+
 Commands using this module can be run in two manners:
 * using *positional* parameters: this is similar to the old way the
 `opensipsctl` tool was working: the parameters passed to the function are

opensipscli-0.4.2/docs/modules/tls.md

@@ -0,0 +1,191 @@
+# OpenSIPS CLI - TLS module
+
+Using the `tls` module, you can generate TLS certificates and private keys.
+
+The module has the following subcommands:
+* `rootCA` - generates a CA (certification authority) self signed certificate
+and private key pair.  These are to be used by a TLS server.
+* `userCERT` - generates a certificate signed by a given CA, a private key and
+a CA list (chain of trust) file.  These are to be used by TLS clients (users).
+* `add` - adds a new TLS domain to the `tls_mgm` table.
+* `update` - changes the columns of an existing TLS domain.
+* `list` - lists the TLS domains provisioned in the `tls_mgm` table.
+* `show` - prints the columns of a TLS domain.
+* `delete` - removes a TLS domain from the `tls_mgm` table.
+
+The `add`, `update`, `list`, `show` and `delete` subcommands provision the
+`tls_mgm` module over the database, where the certificate, private key and CA
+list are stored as BLOB values rather than as paths to files.  A TLS domain is
+identified by its name and its type (`server` or `client`), both passed as
+arguments:
+```
+opensips-cli -x tls delete a.example.org server
+```
+The domain and its type may also be given by name, in which case they can
+appear anywhere among the other columns:
+```
+opensips-cli -x tls delete domain=a.example.org type=server
+```
+Giving one of them both ways at once is an error.  The commands addressing a
+single domain ask for whatever is left out; `add` and `show` default the
+type to `server`, while `update` and `delete` have no default and keep
+asking until one is given, so that they cannot change a different domain than
+the intended one.
+
+`add` and `update` take the remaining `tls_mgm` columns as `column=value`
+arguments, in any order and after the domain and the type:
+```
+opensips-cli -x tls add a.example.org server method=TLSv1_2 verify_cert=1
+```
+The settable columns are `match_ip_address`, `match_sip_domain`, `method`,
+`verify_cert`, `require_cert`, `certificate`, `private_key`, `crl_check_all`,
+`crl_dir`, `ca_list`, `ca_dir`, `cipher_list`, `dh_params` and `ec_curve`.  A
+column that is not given is left to its default in the database schema;
+`update` only changes the columns it is given.
+
+The `certificate`, `private_key`, `ca_list` and `dh_params` columns hold PEM
+content, so their value is the path of the file holding it, and that file is
+read and stored in the table:
+```
+opensips-cli -x tls add a.example.org server \
+	certificate=/etc/opensips/tls/user/user-cert.pem \
+	private_key=/etc/opensips/tls/user/user-privkey.pem
+```
+Every other column is stored as the value it is given, paths included: for
+example, `ca_list` reads the file it points to, while `ca_dir` and `crl_dir`
+keep the directory as such, which is what `tls_mgm` expects of them.
+
+After every change, the `tls_reload` MI command is issued so that a running
+OpenSIPS picks up the new domains.  If OpenSIPS cannot be reached, a warning is
+logged and the domains are loaded at the next restart.
+
+## Configuration
+
+Certificates and private keys can be customized using the following settings:
+
+List of `opensips-cli.cfg` settings for configuring self-signed CA certificates:
+
+* tls_ca_dir - output directory where the cert and key will be written to
+* tls_ca_cert_file - output certificate file path, within `tls_ca_dir`
+* tls_ca_key_file - output private key file path, within `tls_ca_dir`
+* tls_ca_overwrite - set this to "y" in order to overwrite existing files
+* tls_ca_common_name - the address of the website (e.g. "opensips.org")
+* tls_ca_country - the initials of the country (e.g. "RO")
+* tls_ca_state - the state (e.g. "Bucharest")
+* tls_ca_locality - the city (e.g. "Bucharest")
+* tls_ca_organisation - the name of the organisation (e.g. "OpenSIPS")
+* tls_ca_organisational_unit - the organisational unit (e.g. "Project")
+* tls_ca_notafter - the validity period, in seconds (e.g. 315360000)
+* tls_ca_key_size - the size of the RSA key, in bits (e.g. 4096)
+* tls_ca_md - the digest algorithm to use for signing (e.g. SHA256)
+
+List of `opensips-cli.cfg` settings for configuring user certificates:
+
+* tls_user_dir - output directory where the cert and key will be written to
+* tls_user_cert_file - output certificate file path, within `tls_user_dir`
+* tls_user_key_file - output private key file path, within `tls_user_dir`
+* tls_user_calist_file - output CA list file path, within `tls_user_dir`
+* tls_user_overwrite - set this to "y" in order to overwrite existing files
+* tls_user_cacert - path to the input CA certificate
+* tls_user_cakey - path to the input CA private key
+* tls_user_common_name - the address of the website (e.g. "www.opensips.org")
+* tls_user_country - the initials of the country (e.g. "RO")
+* tls_user_state - the state (e.g. "Bucharest")
+* tls_user_locality - the city (e.g. "Bucharest")
+* tls_user_organisation - the name of the organisation (e.g. "OpenSIPS")
+* tls_user_organisational_unit - the organisational unit (e.g. "Project")
+* tls_user_notafter - the validity period, in seconds (e.g. 315360000)
+* tls_user_key_size - the size of the RSA key, in bits (e.g. 4096)
+* tls_user_md - the digest algorithm to use for signing (e.g. SHA256)
+
+List of `opensips-cli.cfg` settings for the `tls_mgm` database subcommands:
+
+* database_tls_url - URL of the database holding the `tls_mgm` table; falls
+back to `database_url`
+* database_tls_name - name of the database; falls back to `database_name`
+
+
+## Examples
+
+To create a self-signed certificate and a private key for rootCA, enter this snippet:
+```
+opensips-cli -x tls rootCA
+```
+Configuration file example for rootCA:
+```
+[default]
+tls_ca_dir: /etc/opensips/tls/rootCA
+tls_ca_cert_file: cacert.pem
+tls_ca_key_file: private/cakey.pem
+tls_ca_overwrite: yes
+tls_ca_common_name: opensips.org
+tls_ca_country: RO
+tls_ca_state: Bucharest
+tls_ca_locality: Bucharest
+tls_ca_organisation: OpenSIPS
+tls_ca_organisational_unit: Project
+tls_ca_notafter: 315360000
+tls_ca_key_size: 4096
+tls_ca_md: SHA256
+```
+
+To create a user certificate signed by the above rootCA, along with a private
+key and a CA list (chain of trust) file:
+```
+opensips-cli -x tls userCERT
+```
+Configuration file example for userCERT:
+```
+[default]
+tls_user_dir: /etc/opensips/tls/user
+tls_user_cert_file: user-cert.pem
+tls_user_key_file: user-privkey.pem
+tls_user_calist_file: user-calist.pem
+tls_user_overwrite: yes
+tls_user_cacert: /etc/opensips/tls/rootCA/cacert.pem
+tls_user_cakey: /etc/opensips/tls/rootCA/private/cakey.pem
+tls_user_common_name: www.opensips.org
+tls_user_country: RO
+tls_user_state: Bucharest
+tls_user_locality: Bucharest
+tls_user_organisation: OpenSIPS
+tls_user_organisational_unit: Project
+tls_user_notafter: 315360000
+tls_user_key_size: 4096
+tls_user_md: SHA256
+```
+
+To provision the certificate generated above as a TLS domain in the database:
+```
+opensips-cli -x tls add a.example.org server \
+	certificate=/etc/opensips/tls/user/user-cert.pem \
+	private_key=/etc/opensips/tls/user/user-privkey.pem \
+	ca_list=/etc/opensips/tls/user/user-calist.pem
+```
+Certificates issued by a public CA are provisioned the same way:
+```
+opensips-cli -x tls add a.example.org server \
+	certificate=/etc/letsencrypt/live/a.example.org/fullchain.pem \
+	private_key=/etc/letsencrypt/live/a.example.org/privkey.pem
+```
+Configuration file example for the `tls_mgm` database subcommands:
+```
+[default]
+database_url: mysql://opensips:opensipsrw@localhost
+database_name: opensips
+```
+
+To renew the certificate of a domain, or to change any of its other columns:
+```
+opensips-cli -x tls update a.example.org server \
+	certificate=/etc/letsencrypt/live/a.example.org/fullchain.pem \
+	private_key=/etc/letsencrypt/live/a.example.org/privkey.pem
+opensips-cli -x tls update a.example.org server cipher_list=HIGH
+```
+
+To inspect and remove the provisioned domains:
+```
+opensips-cli -x tls list
+opensips-cli -x tls show a.example.org server
+opensips-cli -x tls delete a.example.org server
+```

{opensipscli-0.4.0 → opensipscli-0.4.2}/opensipscli/cli.py

@@ -29,7 +29,6 @@ from opensipscli import comm
 from opensipscli import defaults
 from opensipscli.config import cfg
 from opensipscli.logger import logger
-from opensipscli.modules import *
 
 class OpenSIPSCLI(cmd.Cmd, object):
     """
@@ -121,6 +120,10 @@ class OpenSIPSCLI(cmd.Cmd, object):
         self.current_instance = instance
         self.update_logger()
 
+        # import the modules only now, so that their import-time messages
+        # honor the logging level
+        importlib.import_module("opensipscli.modules")
+
         # Update the intro and prompt
         self.intro = cfg.get('prompt_intro')
         self.prompt = '(%s): ' % cfg.get('prompt_name')
@@ -175,7 +178,11 @@ class OpenSIPSCLI(cmd.Cmd, object):
                 continue
             logger.debug("Loaded module '{}'".format(name))
             imod = mod()
-            self.modules[name] = (imod, mod.__get_methods__(imod))
+            methods = mod.__get_methods__(imod)
+            aliases = {}
+            if hasattr(imod, '__get_aliases__'):
+                aliases = imod.__get_aliases__() or {}
+            self.modules[name] = (imod, methods, aliases)
 
     def history_write(self):
         """
@@ -419,7 +426,7 @@ class OpenSIPSCLI(cmd.Cmd, object):
             logger.error("module '{}' expects the following commands: {}".
                    format(module, ", ".join(mod[1])))
             return -1
-        elif cmd and not cmd in mod[1]:
+        elif cmd and cmd not in mod[1] and cmd not in mod[2]:
             logger.error("no command '{}' in module '{}'".
                     format(cmd, module))
             return -1

{opensipscli-0.4.0 → opensipscli-0.4.2}/opensipscli/db.py

@@ -36,17 +36,26 @@ try:
     #from sqlalchemy.engine.url import make_url
 
     sqlalchemy_available = True
+    sqlalchemy_import_error = None
     logger.debug("SQLAlchemy version: %s", sqlalchemy.__version__)
     # always use the vendored shim — the system sqlalchemy-utils package
     # varies a lot across distros (0.36.x ships broken database_exists for
     # PostgreSQL on Bullseye; 0.41.x is required for SA 2.0); the shim is
     # tested against SA 1.3–2.0 and behaves consistently
     from opensipscli.libs import sqlalchemy_utils
+except ImportError as e:
+    # keep the cause around so callers can report it when the database
+    # is actually needed
+    logger.info("sqlalchemy not available: %s", e)
+    sqlalchemy_available = False
+    sqlalchemy_import_error = e
+
+try:
     import pymysql
     pymysql.install_as_MySQLdb()
 except ImportError:
-    logger.info("sqlalchemy not available!")
-    sqlalchemy_available = False
+    # only needed for mysql:// URLs; the other backends work without it
+    pass
 
 SUPPORTED_BACKENDS = [
     "mysql",
@@ -210,7 +219,16 @@ class osdb(object):
 
 	    # TODO: do this only for SQLAlchemy
         try:
-            self.__engine = sqlalchemy.create_engine(db_url, isolation_level='AUTOCOMMIT')
+            if self.dialect == "sqlite":
+                # SQLite only got the AUTOCOMMIT isolation level in SA 1.3.16;
+                # older versions (EL8 ships 1.3.2) reject it with ArgumentError.
+                # Setting the pysqlite isolation_level to None gives the same
+                # autocommit behaviour on every supported SA version.
+                self.__engine = sqlalchemy.create_engine(
+                        db_url, connect_args={'isolation_level': None})
+            else:
+                self.__engine = sqlalchemy.create_engine(
+                        db_url, isolation_level='AUTOCOMMIT')
 
             logger.debug("connecting to %s", db_url)
             self.__conn = self.__engine.connect()
@@ -477,10 +495,10 @@ class osdb(object):
         if not self.__conn:
             raise osdbError("connection not available")
 
-        where_str = self.get_where(filter_keys)
+        where_str, params = self.get_where(filter_keys)
         statement = "DELETE FROM {}{}".format(table, where_str)
         try:
-            self.__conn.execute(text(statement))
+            self.__conn.execute(text(statement), params)
         except sqlalchemy.exc.SQLAlchemyError as ex:
             logger.error("cannot execute query: {}".format(statement))
             logger.error(ex)
@@ -658,13 +676,13 @@ class osdb(object):
         elif type(fields) != list:
             fields = [ fields ]
 
-        where_str = self.get_where(filter_keys)
+        where_str, params = self.get_where(filter_keys)
         statement = "SELECT {} FROM {}{}".format(
                 ", ".join(fields),
                 table,
                 where_str)
         try:
-            result = self.__conn.execute(text(statement))
+            result = self.__conn.execute(text(statement), params)
         except sqlalchemy.exc.SQLAlchemyError as ex:
             logger.error("cannot execute query: {}".format(statement))
             logger.error(ex)
@@ -679,22 +697,18 @@ class osdb(object):
 
     def get_where(self, filter_keys):
         """
-        construct a sql 'where clause' from given filter keys
-        """
-        if filter_keys:
-            where_str = ""
-            for k, v in filter_keys.items():
-                where_str += " AND {} = ".format(k)
-                if type(v) == int:
-                    where_str += str(v)
-                else:
-                    where_str += "'{}'".format(
-                            v.translate(str.maketrans({'\'': '\\\''})))
-            if where_str != "":
-                where_str = " WHERE " + where_str[5:]
-        else:
-            where_str = ""
-        return where_str
+        construct a sql 'where clause' from given filter keys, along with
+        the parameters to bind to it
+        """
+        if not filter_keys:
+            return "", {}
+
+        where_str = ""
+        params = {}
+        for i, (k, v) in enumerate(filter_keys.items()):
+            where_str += " AND {} = :w{}".format(k, i)
+            params["w{}".format(i)] = v
+        return " WHERE " + where_str[5:], params
 
     def get_role(self, role_name="opensips"):
         """
@@ -762,6 +776,8 @@ class osdb(object):
         check for support of a given database dialect via SQLAlchemy
         """
         # TODO: do this only for SQLAlchemy
+        if not sqlalchemy_available:
+            return False
         try:
             sqlalchemy.create_engine('{}://'.format(dialect))
         except sqlalchemy.exc.NoSuchModuleError:
@@ -781,18 +797,13 @@ class osdb(object):
         if not self.__conn:
             raise osdbError("connection not available")
 
-        values = ""
-        for v in keys.values():
-            values += ", "
-            if type(v) == int:
-                values += str(v)
-            else:
-                values += "'{}'".format(
-                        v.translate(str.maketrans({'\'': '\\\''})))
+        cols = list(keys.keys())
+        params = {"v{}".format(i): keys[k] for i, k in enumerate(cols)}
         statement = "INSERT INTO {} ({}) VALUES ({})".format(
-                table, ", ".join(keys.keys()), values[2:])
+                table, ", ".join(cols),
+                ", ".join(":v{}".format(i) for i in range(len(cols))))
         try:
-            result = self.__conn.execute(text(statement))
+            result = self.__conn.execute(text(statement), params)
         except sqlalchemy.exc.SQLAlchemyError as ex:
             logger.error("cannot execute query: {}".format(statement))
             logger.error(ex)
@@ -874,18 +885,16 @@ class osdb(object):
             raise osdbError("connection not available")
 
         update_str = ""
-        for k, v in update_keys.items():
-            update_str += ", {} = ".format(k)
-            if type(v) == int:
-                update_str += str(v)
-            else:
-                update_str += "'{}'".format(
-                        v.translate(str.maketrans({'\'': '\\\''})))
-        where_str = self.get_where(filter_keys)
+        params = {}
+        for i, (k, v) in enumerate(update_keys.items()):
+            update_str += ", {} = :s{}".format(k, i)
+            params["s{}".format(i)] = v
+        where_str, where_params = self.get_where(filter_keys)
+        params.update(where_params)
         statement = "UPDATE {} SET {}{}".format(table,
                 update_str[2:], where_str)
         try:
-            result = self.__conn.execute(text(statement))
+            result = self.__conn.execute(text(statement), params)
         except sqlalchemy.exc.SQLAlchemyError as ex:
             logger.error("cannot execute query: {}".format(statement))
             logger.error(ex)