November 2022 - gerrit-log - lists.osmocom.org

Change in osmo-e1d[master]: avoid segfault in 'show interface' of absent icE1usb

by laforge

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-e1d/+/30021 ) Change subject: avoid segfault in 'show interface' of absent icE1usb ...................................................................... avoid segfault in 'show interface' of absent icE1usb Don't segfault when processing a "show interfaces" for an interface that is configured via VTY but not actually attached/found in the system: usb.c:693:29: runtime error: member access within null pointer of type 'struct e1_usb_intf_data' Depends: https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 Depends: https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 Change-Id: I2ce990bb57f6ae4edb3a99a4b7bf26a49f362410 --- M src/usb.c 1 file changed, 6 insertions(+), 0 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-e1d refs/changes/21/30021/1 diff --git a/src/usb.c b/src/usb.c index fc461c4..ff624ea 100644 --- a/src/usb.c +++ b/src/usb.c @@ -694,6 +694,12 @@ OSMO_ASSERT(intf->drv == E1_DRIVER_USB); + if (!id) { + /* This can happen for statically configured devices (config/vty) which are not + * currently present */ + return snprintf(buf, len, "unknown"); + } + return snprintf(buf, len, "mode=%s, fix=%s, state=%s antenna=%s, tune=%u/%u, freq_est=%u", get_value_string(ice1usb_gpsdo_mode_str, last_st->mode), last_st->valid_fix ? "TRUE" : "FALSE", -- To view, visit https://gerrit.osmocom.org/c/osmo-e1d/+/30021 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-e1d Gerrit-Branch: master Gerrit-Change-Id: I2ce990bb57f6ae4edb3a99a4b7bf26a49f362410 Gerrit-Change-Number: 30021 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-MessageType: newchange

2 years, 7 months

1
0
0 0

Change in osmo-e1d[master]: Initial user manual for osmo-e1d

by laforge

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-e1d/+/30022 ) Change subject: Initial user manual for osmo-e1d ...................................................................... Initial user manual for osmo-e1d Still quite incomplete, but significantly better than nothing. Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281 --- M configure.ac M doc/Makefile.am A doc/manuals/Makefile.am A doc/manuals/chapters/client-interface.adoc A doc/manuals/chapters/drivers.adoc A doc/manuals/chapters/overview.adoc A doc/manuals/chapters/running.adoc A doc/manuals/chapters/tdmoip.adoc A doc/manuals/osmoe1d-usermanual-docinfo.xml A doc/manuals/osmoe1d-usermanual.adoc 10 files changed, 488 insertions(+), 0 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-e1d refs/changes/22/30022/1 diff --git a/configure.ac b/configure.ac index f671591..2d5481f 100644 --- a/configure.ac +++ b/configure.ac @@ -75,6 +75,49 @@ CPPFLAGS="$CPPFLAGS $WERROR_FLAGS" fi + +# Generate manuals +AC_ARG_ENABLE(manuals, + [AS_HELP_STRING( + [--enable-manuals], + [Generate manual PDFs [default=no]], + )], + [osmo_ac_build_manuals=$enableval], [osmo_ac_build_manuals="no"]) +AM_CONDITIONAL([BUILD_MANUALS], [test x"$osmo_ac_build_manuals" = x"yes"]) +AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, [path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals" + fallback]) +if test x"$osmo_ac_build_manuals" = x"yes" +then + # Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback) + if test -n "$OSMO_GSM_MANUALS_DIR"; then + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)" + else + OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)" + if test -n "$OSMO_GSM_MANUALS_DIR"; then + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)" + else + OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals" + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)" + fi + fi + if ! test -d "$OSMO_GSM_MANUALS_DIR"; then + AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.") + fi + + # Find and run check-depends + CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh" + if ! test -x "$CHECK_DEPENDS"; then + CHECK_DEPENDS="osmo-gsm-manuals-check-depends" + fi + if ! $CHECK_DEPENDS; then + AC_MSG_ERROR("missing dependencies for --enable-manuals") + fi + + # Put in Makefile with absolute path + OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")" + AC_SUBST([OSMO_GSM_MANUALS_DIR]) +fi + AC_ARG_ENABLE([external_tests], AC_HELP_STRING([--enable-external-tests], [Include the VTY/CTRL tests in make check [default=no]]), @@ -117,6 +160,7 @@ contrib/systemd/Makefile doc/Makefile doc/examples/Makefile + doc/manuals/Makefile src/Makefile src/octoi/Makefile include/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index 8acb8f8..3cb405e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,4 @@ SUBDIRS = \ examples \ + manuals \ $(NULL) diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am new file mode 100644 index 0000000..79b2778 --- /dev/null +++ b/doc/manuals/Makefile.am @@ -0,0 +1,14 @@ +EXTRA_DIST = \ + osmoe1d-usermanual.adoc \ + osmoe1d-usermanual-docinfo.xml \ + chapters \ + $(NULL) + +if BUILD_MANUALS + ASCIIDOC = osmoe1d-usermanual.adoc + include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc + osmoe1d-usermanual.pdf: $(srcdir)/chapters/*.adoc + + OSMO_REPOSITORY = osmo-e1d + include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc +endif diff --git a/doc/manuals/chapters/client-interface.adoc b/doc/manuals/chapters/client-interface.adoc new file mode 100644 index 0000000..69863d0 --- /dev/null +++ b/doc/manuals/chapters/client-interface.adoc @@ -0,0 +1,72 @@ +[[e1dp]] +== Client Interface + +This chapter documents the _Client interface_ which is used by +application programs wanting to send and/or receive data on the E1 +circuits served by `osmo-e1d`. + +The interface is based on a `unix domain socket` and works in the +following way: + +* `osmo-e1d` implements the server side of a unix domain socket + +* the application program acts as a client program establishing a socket + connection to the e1d unix domain socket +* the application program preforms operations such as opening of a + specific E1 timeslot on a spcific line/interface. +* `osmo-e1d` passes a file descriptor from the daemon to the client + application +* the client application can read/write data from/to the E1 timeslot via + this file descriptor + +This architecture was chosen to allow for the _one file descriptor per +timeslot_ paradigm that is known from other drivers, such as DAHDI. + +Each timeslot of each line on each interface can theoretically be opened +by a different program. This permits for example control/user plane +splits like a signaling gateway + media gateway implemented as separate +processes. + +When opening a timeslot, the client specifies the _mode_. + +* In _RAW mode_, the transparent 64kBps bit-stream is passed over the + per-timeslot file descriptor. This is mostly used for B-channels / + user traffic. +* In _HDLC-FCS mode_, a (software) HDLC processor is instantiated. It + performs flag sequence detection/generation and bit-stuffing. This is + mostly used for D-channels / signalling. + +Details about the messaging on the unix domain socket can be found in +the definitions contained in the `include/osmocom/e1d/proto.h` header +file, as well as the doxygen API documentation generated from it. + +=== `libosmo-e1d` client library + +To simplify interfacing `osmo-e1d` from an application, there is a +companion library called `libosmo-e1d`. + +It contains functions implementing the above-mentioned client interface +protocol and prevents the application developer from having to implement +the low-level bits of this interface. + +The library is licensed under GNU LGPL-3.0-or-later, which is a weak +copyleft license that permits using the library from non-open-source / +proprietary applications. + +The library offers the following functions: + +* initialization / teardown +** `osmo_e1dp_client_create()` +** `osmo_e1dp_client_destroy()` +* information querying +** `osmo_e1dp_client_intf_query()` +** `osmo_e1dp_client_line_query()` +** `osmo_e1dp_client_ts_query()` +* configuration +** `osmo_e1dp_client_line_config()` +* opening of timeslots +** `osmo_e1dp_client_ts_open()` +** `osmo_e1dp_client_ts_open_force()` + +Details about those functions can be found in the definitions contained +in the `include/osmocom/e1d/proto_clnt.h` header file. diff --git a/doc/manuals/chapters/drivers.adoc b/doc/manuals/chapters/drivers.adoc new file mode 100644 index 0000000..e4a3858 --- /dev/null +++ b/doc/manuals/chapters/drivers.adoc @@ -0,0 +1,85 @@ +[[drivers]] +== E1 drivers + +`osmo-e1d` was primarily developed for the icE1usb hardware, but also +supports some other drivers by now. + + +=== The `usb` driver for icE1usb and e1-tracer + +The `usb` driver implements the USB interface first implemented by the +`icE1usb` hardware. + +For more information on the `icEusb`, please see its related user +manual, published at https://downloads.osmocom.org/docs/latest/icE1usb-usermanual.pdf + +Each `icEusb` device implements one E1 interface with up to two E1 +lines. Note that supporting two E1 lines is only supported on very few +select USB host controllers. In most cases, your USB host controller +will only permit using one of the two lines. + +==== Configuration + +`osmo-e1d` will automatically detect any supported USB devices when +starting up. It will dynamically allocate E1 interface and E1 line +numbers to those USB devices. However, the order is not guaranteed and +particularly in case you have multiple devices, it is strongly +recommended to use _static configuration_. + +In this static configuration, you would have a block like + +.Example configuration snippet for an icE1usb +---- + interface 2 icE1usb + usb-serial dc697407e7881531 +---- + +This way you reserve/allocate the E1 interface number 2 for the icE1usb +with serial number dc697407e7881531. The Serial number is unique and +stored in the iSerial string of the USB device descriptor. You can for +example use `lsusb -v -d 1d50: | grep iSerial` to obtain it, or check +the `dmesg` kernel log after plugging in a device. + +==== Using the `usb` driver with `e1-tracer` + +The same driver has been slightly extended to also support the passive, +bi-directional `e1-tracer` hardware. The configuration and use is +identical to the use with the `icE1usb`, with the notable difference +that a passive tracer can obviously only receive data from E1, but not +transmit. The two directions of a E1 circuit are represented as two +lines in `osmo-e1d`. + +=== The `vpair` driver for virtual E1 circuits + +Sometimes it is useful to be able to interface multiple E1-using +applications without a real E1 circuit or any hardware whatsoever. + +This can be used in automatic / virtualized software testing, but also +in case a legacy application is migrate away from real physical E1 +circuits. + +==== Configuration + +The configuration of the `vpair` driver is relatively simple. It +consists of a single `virtual-e1-pair` command. + +.Example configuration snippet for a virtual E1 pair with one E1 line +---- +e1d + virtual-e1-pair 1 +---- + +The above example will create a virtual pair of E1 interfaces, each +of those interface with one E1 line. + +.Log output of the example configuration for 1 virtual pair +---- +intf_line.c:184 (I0) Created +intf_line.c:285 (I0:L0) Created +intf_line.c:184 (I1) Created +intf_line.c:285 (I1:L0) Created +---- + +You can subsequently use the Lines just like you would use physical E1 +lines. Any data you transmit on one line will be received on the other +line, and vice versa. diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 0000000..31d8678 --- /dev/null +++ b/doc/manuals/chapters/overview.adoc @@ -0,0 +1,105 @@ +== Overview + +=== About this manual + +This manual should help you getting started with the `osmo-e1d` software. +It will cover aspects of configuring and running `osmo-e1d` as well as some +introduction about its internal architecture and external interfaces. + +=== About `osmo-e1d` + +`osmo-e1d` is a driver (implemented as userspace daemon) for a variety of hardware +related to the E1 (TDM) interface, such as + +* the `icEusb` USB attached E1 interface +* the `e1-tracer` USB attached passive E1 tracer + +=== Credits + +`osmo-e1d` was originally developed in 2019 by Sylvain Munaut alongside +the icE1usb project. It subsequently got improved and extended by Harald +Welte. + +=== Architecture + +`osmo-e1d` is a driver system for E1 circuits, which are sometimes also called +primary rate (PRI). It typically sits between an E1 hardware interface beneath +it and application software above it. + +.How osmo-e1d fits in the overall system achitecture +[graphviz] +---- +digraph G{ + //rankdir = LR; + Application -> loa; + pipe -> e1d [style=dashed]; + loa -> e1d; + + e1d -> HW; + e1d -> vpair; + + HW -> BTS; + + {rank=same; + Application [label="Application\nosmo-nitb / osmo-bsc"]; + pipe [label="osmo-e1d-pipe\nfor testing", style=dashed]; + } + e1d [label="osmo-e1d", color=red]; + loa [label="libosmo-abis\ne1_input"]; + HW [label="E1 Hardware"]; + vpair [label="Virtual E1 pair"]; +} +---- + +Contrary to older E1 drivers such as DAHDI or mISDN, `osmo-e1d` runs entirely in userspace, +without a need for kernel drivers. This is obviously less computationally efficient, +but has other advantages, such as working on unmodified Linux kernels / operating systems, +and with a lower risk of software bugs affecting overall system +stability. Particularly at low E1 port density and modern hardware, the +lower efficiency is not expected to make a big difference. + +==== E1 Interfaces + +In `osmo-e1d` language, an _E1 Interface_ is some kind of underlying hardware that contains one or more +_Lines_. Interfaces are numbered from 0..N and are often abbreviated e.g. as `I0` for Interface 0. + +==== E1 Lines + +In `osmo-e1d` language, an _E1 Line_ represents one single E1 circuit within an _E1 Interface_. + +=== Hardware support + +`osmo-e1d` currently supports the following hardware: + +* Osmocom icE1usb +* Osmocom e1-tracer +* Virtual pair of E1 circuits + +==== icE1usb + +The Osmocom icE1usb is an OSHW implementation of a USB-attached hardware +interface for up to two E1 circuits (lines). + +For more information on the Osmocom icE1usb, see + +* data sheet: https://www.sysmocom.de/downloads/icE1usb_data_sheet.pdf +* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/ICE40_E1_USB_interface +* user manual: https://ftp.osmocom.org/docs/latest/icE1usb-usermanual.pdf +* product page: https://www.sysmocom.de/products/lab/icE1usb + +==== e1-tracer + +The Osmocom e1-tracer is an OSHW implementation of a passive, +high-impedance bi-directional E1 tap/tracer/sniffer. It can be used to +capture traffic on an unmodified E1 interface. + +For more information on the Osmocom e1-tracer, see + +* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/E1_tracer +* user manual: https://ftp.osmocom.org/docs/latest/e1tracer-usermanual.pdf + +==== vpair + +The osmo-e1d _vpair_ is not actual hardwarr, but a virtual pair of E1 +interfaces. It can be used to test E1-using applications without +involving a hardware E1 circuit. diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc new file mode 100644 index 0000000..f1841fd --- /dev/null +++ b/doc/manuals/chapters/running.adoc @@ -0,0 +1,25 @@ +[[running]] +== Running osmo-e1d + +The `osmo-e1d` executable offers the following command-line arguments: + +=== SYNOPSIS + +*osmo-e1d* [-h] [-d 'DBGMASK'] [-c 'CONFIGFILE'] + +=== OPTIONS + +*-h, --help*:: + Print a short help message about the supported options. +*-V, --version*:: + Print the version of osmo-e1d. +*-d, --debug 'DBGMASK','DBGLEVELS'*:: + Set the log subsystems and levels for logging to stderr. This + has mostly been superseded by VTY-based logging configuration, + see <<logging>> for further information. +*-c, --config-file 'CONFIGFILE'*:: + Specify the file and path name of the configuration file to be + used. If none is specified, use `osmo-bsc.cfg` in the current + working directory. + +include::../common/snippets/systemd.adoc[] diff --git a/doc/manuals/chapters/tdmoip.adoc b/doc/manuals/chapters/tdmoip.adoc new file mode 100644 index 0000000..2250f05 --- /dev/null +++ b/doc/manuals/chapters/tdmoip.adoc @@ -0,0 +1,68 @@ +[[octoi]] +== OCTOI TDMoIP mode + +Instead of providing a programmatic client interface (<<client>>) enabling +external applications timeslot-granular access to the data of a E1 line, +`osmo-e1d` also supports an entirely separate mode of operation: +_TDMoIP using the OCTOI (Osmocom Community TDMoIP) protocol_. + +In this mode of operation, osmo-e1d acts as interface between an E1 line +and a remote system over UDP/IP. This allows you to transparently pass +an E1 line over an IP network such as the Internet. + +`osmo-e1d` can operate either as client or as server for the OCTOI protocol. + +=== osmo-e1d as OCTOI client + +Below is an example configuration snippet for operating as an OCTOI client. + +.Configuration snippet for operating as an OCTOI client +---- +e1d + interface 0 icE1usb + usb-serial dc697407e7881531 + line 0 + mode e1oip <1> +octoi-client 192.168.7.2 10013 <2> + local-bind 0.0.0.0 3333 <3> + account foobar <4> + mode ice1usb + ice1usb serial-number dc697407e7881531 <5> + ice1usb line-number 0 +---- +<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall + be used in `e1oip` mode. +<2> we instantiate an OCTOI client to the remote IP 192.168.7.2 / UDP port 10013 +<3> we specify to bind locally to INADDR_ANY and local UDP port 3333 +<4> we specify the account/user name to tell the server is `foobar` +<5> we specify that this OCTOI client instance shall use the icE1usb device with the given serial number. This + must match the serial number used above when configuring the icE1usb line mode. + +There can of course be any number of E1 interfaces/lines and clients; the example just shows one for clarity. + +=== osmo-e1d as OCTOI server + +Below is an example configuration snippet for operating as an OCTOI server. + +.Configuration snippet for operating as an OCTOI server +---- +e1d + interface 0 icE1usb + usb-serial dc697407e7881531 + line 0 + mode e1oip <1> +octoi-server + local-bind 0.0.0.0 9999 <2> + account foobar <3> + mode ice1usb + ice1usb serial-number dc697407e7881531 <4> + ice1usb line-number 0 +---- +<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall + be used in `e1oip` mode. +<2> we bind the OCTOI server to UDP port 9999 of INADDR_ANY +<3> we specify a user account `foobar` +<4> we connect the user account `foobar` to the icE1usb serial number / line number specified above + +There can of course be any number of E1 interfaces/lines and user accounts; the example just shows one for +clarity. diff --git a/doc/manuals/osmoe1d-usermanual-docinfo.xml b/doc/manuals/osmoe1d-usermanual-docinfo.xml new file mode 100644 index 0000000..714989b --- /dev/null +++ b/doc/manuals/osmoe1d-usermanual-docinfo.xml @@ -0,0 +1,31 @@ + +<authorgroup> + <author> + <firstname>Harald</firstname> + <surname>Welte</surname> + <email>hwelte(a)sysmocom.de</email> + <authorinitials>HW</authorinitials> + <affiliation> + <shortaffil>sysmocom</shortaffil> + <orgname>sysmocom - s.f.m.c. GmbH</orgname> + <jobtitle>Managing Director</jobtitle> + </affiliation> + </author> +</authorgroup> + +<copyright> + <year>2016-2022</year> + <holder>sysmocom - s.f.m.c. GmbH</holder> +</copyright> + +<legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being just 'Foreword', + 'Acknowledgements' and 'Preface', with no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + </para> +</legalnotice> diff --git a/doc/manuals/osmoe1d-usermanual.adoc b/doc/manuals/osmoe1d-usermanual.adoc new file mode 100644 index 0000000..58bd20f --- /dev/null +++ b/doc/manuals/osmoe1d-usermanual.adoc @@ -0,0 +1,43 @@ +:gfdl-enabled: + +osmo-e1d User Manual +==================== +Harald Welte <hwelte(a)sysmocom.de> + +include::./common/chapters/preface.adoc[] + +include::{srcdir}/chapters/overview.adoc[] + +include::./common/chapters/installation.adoc[] + +include::{srcdir}/chapters/running.adoc[] + +include::{srcdir}/chapters/client-interface.adoc[] + +include::{srcdir}/chapters/drivers.adoc[] + +include::{srcdir}/chapters/tdmoip.adoc[] + +//include::{srcdir}/chapters/control.adoc[] + +include::./common/chapters/counters-overview.adoc[] + +//include::{srcdir}/chapters/counters.adoc[] + +include::./common/chapters/vty.adoc[] + +include::./common/chapters/logging.adoc[] + +//include::{srcdir}/chapters/configuration.adoc[] + +include::./common/chapters/vty_cpu_sched.adoc[] + +//include::./common/chapters/control_if.adoc[] + +include::./common/chapters/port_numbers.adoc[] + +include::./common/chapters/bibliography.adoc[] + +include::./common/chapters/glossary.adoc[] + +include::./common/chapters/gfdl.adoc[] -- To view, visit https://gerrit.osmocom.org/c/osmo-e1d/+/30022 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-e1d Gerrit-Branch: master Gerrit-Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281 Gerrit-Change-Number: 30022 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-MessageType: newchange

2 years, 7 months

1
0
0 0

Change in pysim[master]: contrib/jenkins.sh: split test/pylint/docs

by daniel

Attention is currently required from: osmith, pespin. daniel has posted comments on this change. ( https://gerrit.osmocom.org/c/pysim/+/30004 ) Change subject: contrib/jenkins.sh: split test/pylint/docs ...................................................................... Patch Set 1: Code-Review+1 -- To view, visit https://gerrit.osmocom.org/c/pysim/+/30004 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: pysim Gerrit-Branch: master Gerrit-Change-Id: I5245c529db729e209d78a02ab9c917a90d0e0206 Gerrit-Change-Number: 30004 Gerrit-PatchSet: 1 Gerrit-Owner: osmith <osmith(a)sysmocom.de> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: daniel <dwillmann(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: pespin <pespin(a)sysmocom.de> Gerrit-Attention: osmith <osmith(a)sysmocom.de> Gerrit-Attention: pespin <pespin(a)sysmocom.de> Gerrit-Comment-Date: Sat, 05 Nov 2022 21:04:27 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: doc: Add a general chapter on installation of the Osmocom software

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 ) Change subject: doc: Add a general chapter on installation of the Osmocom software ...................................................................... doc: Add a general chapter on installation of the Osmocom software This is just a very high-level overview on the different options. Change-Id: Ia13929a7f932e0c30b9d564b76ada1549ef2a589 --- A common/chapters/installation.adoc 1 file changed, 68 insertions(+), 0 deletions(-) Approvals: laforge: Looks good to me, approved; Verified fixeria: Looks good to me, but someone else must approve diff --git a/common/chapters/installation.adoc b/common/chapters/installation.adoc new file mode 100644 index 0000000..a3193fa --- /dev/null +++ b/common/chapters/installation.adoc @@ -0,0 +1,68 @@ +== Installation + +This section is a general section providing a high-level overview how to +install Osmocom software on your GNU/Linux system. + +It is important that you choose one of the options outlined below. +Trying to mix some packages from a distribution with some packages from +osmocom.org while building some other parts from source is likely asking +for troubles that could be avoided if you stick to all osmocom software +from either one of those sources, without mixing + matching. + +=== Official Osmocom Binary Packages + +The Osmocom project packages most of its software as binary packages for +a variety of GNU/Linux distributions, both in `rpm` and `dpkg` package +formats. + +For the most up-to-date information, please check out the related wiki +page at https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages + +At the time of this writing there are two main flavours: + +* the `latest` feed (containing the latest tagged version of each + program). See https://osmocom.org/projects/cellular-infrastructure/wiki/Latest_Builds +* the `nightly` feed (containing automatic nightly builds of each + program). See https://osmocom.org/projects/cellular-infrastructure/wiki/Nightly_Builds + +=== Distribution Binary Packages + +Your GNU/Linux distribution may contain packages of Osmocom software. If you use those +packages, please look for any distributions-specific information on how those packages +might deviate from upstream, such as for example on Debian GNU/Linux the files located in +`/usr/share/doc/osmo-*/README.Debian`. + +Please note that Distribution packages usually lag behind the official +_upstream_ packages the Osmocom project releases. It is a matter of +personal preference or policy which packages you use. + + +=== Building from source code + +All of Osmocom is Open Source software, so of course the full source +code of the related software is released, and you are free to download, +build, explore it and hack on it. + +The official location for all osmocom source code is at https://gitea.osmocom.org/ + +However, if you are just a normal user and not a developer familiar with +classic C development on GNU/Linux, we *strongly recommend* you to use +some of the binary package options indicated above. + +If you know your way around git, make, autotools, pkg-config, etc. by all +means, go ahead, don't be discouraged. We just want to avoid normal +users from having to work with unfamiliar tools and wasting time on +getting software to build, rather than actually using it. + +Some general (possibly outdated) instructions on how to build Osmocom +software from source can be found at +https://osmocom.org/projects/cellular-infrastructure/wiki/Build_from_Source + +In general, the usual approach is to + +* start with `libosmocore` and all the required librarires and build + them in order until you have the full chain of dependencies in place. + As a final step, build the actual application you want to use. +* perform `autoreconf -fi`, `./confiugre` and `make install` for each of + the projects. Check the `./configure --help` output to see which + optional compile-time features you might want to enable or disable. -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: Ia13929a7f932e0c30b9d564b76ada1549ef2a589 Gerrit-Change-Number: 30020 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-MessageType: merged

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: doc: Add a general chapter on installation of the Osmocom software

by laforge

laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 ) Change subject: doc: Add a general chapter on installation of the Osmocom software ...................................................................... Patch Set 2: Verified+1 Code-Review+2 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: Ia13929a7f932e0c30b9d564b76ada1549ef2a589 Gerrit-Change-Number: 30020 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Comment-Date: Sat, 05 Nov 2022 21:00:20 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: doc: Add a general chapter on installation of the Osmocom software

by laforge

laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 ) Change subject: doc: Add a general chapter on installation of the Osmocom software ...................................................................... Patch Set 1: Verified+1 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: Ia13929a7f932e0c30b9d564b76ada1549ef2a589 Gerrit-Change-Number: 30020 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Comment-Date: Sat, 05 Nov 2022 21:00:11 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: add a documentation snippet for systemd services

by laforge

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 ) Change subject: add a documentation snippet for systemd services ...................................................................... add a documentation snippet for systemd services ... this can be included from the various user manuals to insert some general language about the systemd service units we ship, and a few key systemd commands to get users started. Change-Id: I8b04047cbc4097676d69fad794bb3139c05a4a5f --- A common/snippets/systemd.adoc 1 file changed, 70 insertions(+), 0 deletions(-) Approvals: Jenkins Builder: Verified laforge: Looks good to me, approved diff --git a/common/snippets/systemd.adoc b/common/snippets/systemd.adoc new file mode 100644 index 0000000..671dab1 --- /dev/null +++ b/common/snippets/systemd.adoc @@ -0,0 +1,70 @@ +=== Running as a systemd service + +Most modern GNU/Linux distributions use `systemd` to manage processes. +We provide an example systemd service unit file in the +`contrib/systemd/` sub-directory of the source code. + +Please see your distribution documentation and/or the generic systemd +user manuals for more in-depth information. + +The included systemd service unit file assumes your configuration file +is stored in `/etc/osmocom/`, but feel free to adjust this according to +your local environment. + +This service unit file is also what is used (and installed) by the +official dpkg and rpm packages published by Osmocom. For more +information, see +https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages + +On a system utilizing this systemd service unit, you can use the +following standard commands: + +==== Starting a service + +.Example shell command to start the osmo-bsc service +---- +# systemctl start osmo-bsc +---- +==== Stopping a service + +.Example shell command to stop the osmo-bsc service +---- +# systemctl stop osmo-bsc +---- + +==== Enabling a service for automatic start on boot + +.Example shell command to enable the osmo-bsc service +---- +# systemctl enable osmo-bsc +---- + +NOTE: This will only affect service starting at the next system +boot; it will not start the service if it is not running right now. + +==== Disabling a service from automatic start on boot + +.Example shell command to disable the osmo-bsc service +---- +# systemctl disable osmo-bsc +---- + + +==== Checking current status of a service + +.Example shell command to check the status of osmo-e1d +---- +# systemctl status osmo-e1d +● osmo-e1d.service - Osmocom E1 Interface Daemon + Loaded: loaded (/etc/systemd/system/osmo-e1d.service; enabled; vendor preset: enabled) + Active: active (running) since Tue 2022-11-01 13:12:54 CET; 4 days ago + Main PID: 629 (osmo-e1d) + Tasks: 2 (limit: 4673) + Memory: 2.0M + CPU: 6min 8.464s + CGroup: /system.slice/osmo-e1d.service + └─629 /usr/local/bin/osmo-e1d -c /etc/osmocom/osmo-e1d.cfg + +Nov 03 19:22:56 divo osmo-e1d[629]: Thu Nov 3 19:22:56 2022 DE1D usb.c:734 (I0) GPS antenna status ch> +Nov 03 19:23:00 divo osmo-e1d[629]: Thu Nov 3 19:23:00 2022 DE1D usb.c:734 (I0) GPS antenna status +---- -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: I8b04047cbc4097676d69fad794bb3139c05a4a5f Gerrit-Change-Number: 30019 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-CC: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-MessageType: merged

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: doc: Add a general chapter on installation of the Osmocom software

by laforge

laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 ) Change subject: doc: Add a general chapter on installation of the Osmocom software ...................................................................... Patch Set 1: Code-Review+2 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30020 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: Ia13929a7f932e0c30b9d564b76ada1549ef2a589 Gerrit-Change-Number: 30020 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-Comment-Date: Sat, 05 Nov 2022 21:00:00 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: add a documentation snippet for systemd services

by laforge

Attention is currently required from: fixeria. laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 ) Change subject: add a documentation snippet for systemd services ...................................................................... Patch Set 2: Code-Review+2 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: I8b04047cbc4097676d69fad794bb3139c05a4a5f Gerrit-Change-Number: 30019 Gerrit-PatchSet: 2 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge(a)osmocom.org> Gerrit-CC: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Attention: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Comment-Date: Sat, 05 Nov 2022 20:59:58 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

Change in osmo-gsm-manuals[master]: add a documentation snippet for systemd services

by laforge

Attention is currently required from: fixeria. laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 ) Change subject: add a documentation snippet for systemd services ...................................................................... Patch Set 1: (3 comments) File common/snippets/systemd.adoc: https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019/comment/95b00868_7a6d… PS1, Line 7: Pleas > type: please Done https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019/comment/47df4860_1326… PS1, Line 10: file > document/manual maybe? It refers to the systemd service unit file we ship, not this document. I've expanded it. https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019/comment/99aaa873_0559… PS1, Line 41: Note > AFAIR, you can use 'NOTE: ' to make it pretty formatted. Done -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/30019 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: I8b04047cbc4097676d69fad794bb3139c05a4a5f Gerrit-Change-Number: 30019 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-Reviewer: Jenkins Builder Gerrit-CC: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Attention: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-Comment-Date: Sat, 05 Nov 2022 19:55:11 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: fixeria <vyanitskiy(a)sysmocom.de> Gerrit-MessageType: comment

2 years, 7 months

1
0
0 0

2025

2024

2023

2022

gerrit-log November 2022