This article is obsolete.
Use the online YumaPro Source Code Guide instead.
https://docs.yumaworks.com/en/latest/ypsource/index.html
README Section
https://docs.yumaworks.com/en/latest/ypsource/yumapro-readme.html
The YumaPro server source code is very modular. Various protocol and feature options can be added or removed using make command line options.
The current list of make flags is listed in the README file in the top-level of the source distribution.
The make flags can be used to add features that are not enabled in the binary distribution.
Typically they are used to build the smallest possible image with the features needed.
Always check the README file in the top-level of the source distribution.
This copy may be out of date!!
This README is for the 21.10 release train.
YumaPro README
Last Updated: 2021-10-25
Pre-Build steps:
- set netconf/src/platform/platform.profile details if needed
- see procdefs.h in this directory for common H defs
- CFLAGS and other make details are here
- To build:
> cd to the yumapro top directory
> make [Build Variables]
> sudo make [Buiald Variables] install
Build Variables:
BASIC=1: build yumapro-sdk-basic package
Used by YumaWorks packaging only. Do Not Use!
BITBAKE=1: build for Yocto/bitbake environment. Should set
NO_LIBSSH2=1 and NO_LIBSSL=1 if building yp-shell.
Can also use STATIC=1 and STATIC_SERVER=1.
Do not use UCLINUX=1.
BUILD_LIBS_ONLY=1: build only the libraries (static and or dynamic)
Do not build the SDK applications.
Do not use dl library in the yangcli_show_extern.cpp file
CENTOS5=1: build for the CentOS 5.10 platform.
Must also use LIB64=1 for x86_64 architecture.
CLANG=1: use clang instead of gcc for the C compiler
and use clang++ instead of g++ for the C++ compiler and linker
Default is to use gcc. Ignored if any of these flags set:
- CROSS_TARGET
- PACKAGE_BUILD
- GPROFILE
CLANG_ASAN=1: use clang in LeakSanitizer mode; For debugging
only; will force the compiler and linker to use clang
and add flags such as -fsanitize=address
COVERITY=1: special flag used with MAC=1 to allow Coverity
Static Analysis tools to run on Ubuntu but build with
MAC=1 compiler flags. DO NOT USE THIS FLAG FOR A REAL BUILD.
CROSS_TARGET=<string>: Define the prefix to use for a cross
target toolchain. Example CROSS_TARGET=arm-linux-gnueabi-
Note that cross compiling requires that the target architecture
linker finds the correct external libraries such as libxml2
Do not use this parameter for uCLinux. Use UCLINUX=1
Do not use this parameter for Yocto. Use BITBAKE=1
The tool names will be appended to the $(CROSS_TARGET)
value if it is set. E.g. $(CROSS_TARGET)gcc will resolve
to arm-linux-gnueabi-gcc
CYGWIN=1: build on windows within cygwin environment
(NOT SUPPORTED!)
DEBIAN=1: set for Ubuntu packaging build; do not use
in normal builds, Used by YumaWorks packaging only. Do Not Use!
DEBIAN_MAKE=1: set for ubuntu packaing build; do not use
in normal builds; Indicates compile phase of build
Used by YumaWorks packaging only. Do Not Use!
DEBUG=1: set to add gdb symbols instead of -O2;
does not remove the #ifdef DEBUG function
NULL pointer checks in external functions
DEBUG2=1: set to enable extra debugging code; DEBUG=1
must also be set
DEBUG_LOG_TLS=1: set to enable output buffer tracing
for netconfd-pro using WITH_OPENSSL=1 on a NETCONF over TLS session
This option may be a security risk since the raw buffer output
is not pre-screened for passwords or other sensitive data
The log-level must be set to debug2 or higher for the buffer to
be logged
DESTDIR=string: set the debian target build (default NULL)
DOC=1: debian packaging build flag to build the yuma-doc package.
Do not use in normal builds
This is used for yumapro 13.04, but just to build docs, not
create a separate package for docs
DOCDIR=/path/to/docs: set to override the default location
to install user manuals, which is $(PREFIX)/share/doc/yumapro
with default prefix is /usr/share/doc/yumapro
ETC_PREFIX=string: set the top etc dir (after DESTDIR)
default: /etc
EVAL=1: build the evaluation version of the YumaPro software
Used by YumaWorks packaging only. Do Not Use!
The following server restrictions will apply:
- 250 requests before error returned for every request
- 10 sessions
EVERYTHING=1: build all optional code modules. This flag cannot be
be used if DEBIAN=1 is set. Do not use for packaging builds
Equivalent to:
TIMER_MONO_CLOCK=1
WITH_CALLHOME=1
WITH_CLI=1
WITH_CURL=1
WITH_IETF_INTERFACES=1
WITH_GET2_TEST=1
WITH_GET3_TEST=1
WITH_HOOKS_TEST=1
WITH_HOOKS_TEST_SILSA=1
WITH_LIB_SHOW=1
WITH_LIB_SYSTEM=1
WITH_OPENSSL=1
WITH_RESTCONF=1
WITH_SIL_ERROR=1
WITH_SUPPORT_SAVE=1
WITH_TEMPLATES=1
WITH_YANGMAP=1
WITH_YANG_PUSH=1
WITH_YCONTROL=1
WITH_YP_HA=1
WITH_YUMA_ARP=1
WITH_YUMA_INTERFACES=1
WITH_YUMA_PROC=1
EXTRA_CFLAGS=<string> : Additional compiler flags to add to the CFLAGS
directive. It will be added to CPPFLAGS as well for C++ compilation
FREEBSD=1: Build for a FreeBSD platform
FORCE_YUMA_HOME=1: use when building SIL libraries to
link against a development version of yuma.
The YUMA_HOME environment variable must be set,
and it must point to the 'netconf' directory:
Bash example using 'mybranch':
export YUMA_HOME=/home/andy/swdev/yuma/trunk/branches/mybranch/netconf
The yuma include (H) files from $(YUMA_HOME)/src/*
will be used instead of the system H files in /usr/include/yuma.
The libagt and libncx libraries from $(YUMA_HOME)/target/lib
will be used instead of the system libraries in /usr/lib or /usr/lib64.
The static versions (libagt.a and libncx.a) will be expected if
STATIC=1 is also set. Otherwise the dynamic library versions
will be expected instead.
FULL_STATIC=1: solve linking problems forcing static versions
of all external libraries (used only by debian package build)
This is deprecated and no longer used in any packaging builds
GO_BIN=<dirspec>: specify the $GOBIN variable dirspec to use when
building YP-gNMI application. Default is $HOME/go/bin.
Ignored if PACKAGE_BUILD=1 is also used.
GO_PATH=<dirspec>: specify the $GOPATH variable dirspec to use when
building YP-gNMI application. Default is $HOME/go.
Ignored if PACKAGE_BUILD=1 is also used.
GPROFILE=1: add -pg to the CFLAGS to enable GCC profiling
The STATIC=1 option should also be used.
GUI_LOGGING=1: internal flag used to build libyumapro_ncx
without the log_common and log_append functions so the
Qt version of these functions can be used instead
HOST=string: standard make variable for cross-compile
Must be set correctly together with CROSS_TARGET
Example:
make HOST=mips64-octeon-linux-gnu CROSS_TARGET=mips64-octeon-linux-gnu-
INC_PREFIX=string: set the base string for the include path
The default is $(DESTDIR)$(INSTALL_PREFIX)/include
Used for cross-compiling to change the location for
all built-in include file searches. The USER_INC parameter
can be used to inject -I directives into the compiler command.
The INC_PREFIX and USER_INC parameters can be used together.
INSTALL_PREFIX=string: set the top install dir (after DESTDIR)
default for all but MacOSX: /usr
default for MacOSX: /usr/local
LIB_PREFIX=string: set the base string for the library path
for linking. The default is $(INSTALL_PREFIX)/lib
Used for cross-compiling to change the location for
all built-in library searches. The USER_LIB parameter
can be used to inject -L directives into the linker command.
The LIB_PREFIX and USER_LIB parameters can be used together.
LIB64=1: install and look for SIL libs in /usr/lib64/yuma
instead of /usr/lib/yuma (used by FC14 64 bit)
MAC=1: set to compile for MacOsX
MANDIR=/path/to/man: set to override the default location
to install man pages, which is $(PREFIX)/share/man/man.1
with default prefix is /usr/share/man/man.1
MCHECK=1: enables mcheck heap corruption checking
Used when getting heap corruption errors
Run mcheck(0) in the gdb debugger as needed
MEMTRACE=1: enables mtrace debugging
Used when Memory leak error message printed upon exit.
Need to install glibc-utils for the 'mtrace' program.
Tools will generate an 'mtracefile' in the CWD.
Run mtrace /path/to/program ./mtracefile
MODULES=1: used in debian build only to install just the
YumaPro YANG Modules files for packaging
NETCONFD_LIB=1: build the netconfd-pro server as a static
library for uCLinux or BusyBox. The netconfd-pro code will be
built as a static library instead of a stand-alone program.
Default target will be /usr/lib/libyumapro_netconfd-pro.a
NO_LIBSSH2=1: removes libssh2 code from build; used for
uCLinux which only supports yp-shell, not yangcli-pro
This will remove NETCONF over SSH support from the mgr and
ycli directories. Do not use if building yangcli-pro.
NO_LIBSSL=1: removes libssl code from build; used for
uCLinux which only supports yp-shell, not yangcli-pro
This will remove RESTCONF over SSL support from the mgr and
ycli directories. Do not use if building yangcli-pro.
NO_LIBTECLA=1: removes libtecla usage and linkage from from
code for libyumapro_ycli. This is used when the libraries
are built for the yuma-bench GUI code. Do not use unless
the BUILD_LIBS_ONLY=1 flag is also used.
NO_YPACK=1: do not use the YPACK macro to pack some structures
This will cause more memory to be used, but may be needed if the
target platform does not support it. YPACK is only used if __GNUC__
macro is set. Refer to netconf/src/platform/procdefs.h for details.
NOTOASTER=1: disables building the example toaster SIL
PACKAGE=<pkgname>: set for Ubuntu packaging build;
do not use in normal builds. Needed to pick the variant
that is being installed in a dummy dir and packaged
Values:
CLIENT: used in debian build only to install just the
yangcli-pro files for packaging
CLIENT2: used in debian build only to install just the
yangcli-pro, yangdump-pro, and yangdiff-pro files for packaging
DOCS: used with DOC=1 debian build only to build the
yumapro-docs package
DOCS2: used with DOC=1 debian build only to build the
yumapro-client-docs package
COMPILER: used in debian build only to install just the
yangdump-pro files for packaging
DEVELOPER: used in debian build only to install all of the
YumaPro user binaries (including developer files)
SERVER: used in debian build only to install just the
YumaPro Server files for packaging to run on an embedded
system (NOT USED OR SUPPORTED)
TOOLS: used in debian build only to install all of the
developer tools. Similar to DEVELOPER but does not install
any server binaries.
USER: used in debian build only to install all of the
YumaPro user binaries (no developer files) (NOT USED OR SUPPORTED)
PACKAGE_BUILD=1: set in debian and fedora packlaging scripts
to indicate a packaging build is in progress.
Replaces usage of RELEASE=N or PRODUCTION=1.
PACKAGE_HOST_BUILD=1: set in debian and fedora packaging scripts
by the host machine setting up the sources; Use with DOC=1.
This sets up $HOME/Packaging/yuma_docs so the packaging
builds have PDF and HTML files already made for the release
PREFIX=string: set the top install dir (after DESTDIR)
default: /usr
!!! NO LONGER SUPPORTED OR USED !!!
!!! SEE INSTALL_PREFIX INSTEAD !!!
PRODUCTION=1: disables the --DDEBUG flag definition
in compilation so all #ifdef DEBUG code is removed
PTHREADS=1: generate a threaded version of the server. Adds
'-pthread' to the gcc CFLAGS and links with the pthread
library (see pthread.h).
RELEASE=N: sets the version to ver-release instead of
version.svnversion
SHLIB_NCX=1: used in debian build only to install just the
YumaPro Server libncx files for packaging
This is not used in yumapro 13.04+.
STATIC=1:set to use static libraries such as libncx.a,
instead of dynamic libraries like libncx.so
STATIC_LIBSYSTEM=static-libspec
The relative or absolute filespec representing the
static libyp_system library. Used when STATIC_SERVER=1/
Used from the netconf/src/netconfd-pro directory.
Default: ../../../libsystem/lib/libyp_system-static.a
STATIC_SERVER=1:set to use force the server to not use
any dynamic linked SIL code. The -dl linker option will not be
used and the dlopen, dlclose type of SIL invocation
will not be used. The server will expect the STATIC_LIBSYSTEM
library to be available when netconfd-pro is linked
STATIC_SIL=<string>
This is used to link static SIL libraries into the netconfd-pro
program, using the STATIC_SERVER=1 flag and optionally the
NETCONFD_LIB=1 flag. See the README-STATIC-SIL.txt file
for more details
STATIC_SILSA=<string>
This is used to link static SIL-SA libraries into the sil-sa-app
or combo-app programs. See the README-STATIC-SILSA.txt file
for more details
TEST=1: make will include the 'netconf/test' directory
Run this command before make test, e.g.
make TEST=1; make test; sudo make install
Can be run from top or netconf directory
TIMER_MONO_CLOCK=1: make will use clock_gettime() for server
timers instead of time(). This also requires _POSIX_TIMERS
and _POSIX_MONOTONIC_CLOCK be defined. The system clock
can be changed by settimeofday() which can affect timers.
This option is enabled by EVERYTHING=1.
NOFLOAT=1: disable use of double and tgmath.h; XPath eval
of complex numbers will cause invalid results;
Cygwin does not support complex.h
PIPE_RESTRICTED=1: Affects yp-shell and yangcli-pro only;
Causes the pipe command to be restricted to the sget, sget-config
and show commands. Default is to allow pipe command on any command
UCLINUX=1: build a small static server for the uCLinux OS.
The netconfd-pro, netconf-subsystem-pro, and yp-shell programs
are supported. No distributed services are supported such
as YP-HA, DB-API, SIL-SA. No ypwatcher support. Need to
use flags: STATIC=1 STATIC_SERVER=1 NO_LIBSSH2=1 NO_LIBSSL=1
This platform is not officially supported because the dropbear
SSH performance is so slow that it is operationally unusable.
If dropbear performance is ever improved this may change.
USE_WERROR=1: use -Werror in the compile process
Default is not to use -Werror.
USER_SERVER_INC=string: specify some include directives (-I)
to be added to the make command CINC variable.
The flags apply to the server only.
This parameter is obsolete. Use USER_INC instead
for cross-compiling.
USER_SERVER_LIB=string: specify some include directives (-L, -l)
to be added to the netconfd-pro make command LIBS variable
The flags apply to the netconfd-pro program only.
This parameter is obsolete. Use USER_LIB instead
for cross-compiling.
USER_INC=string: specify some include directives (-I)
to be added to the compile command. This is
used to provide include files from a different
location than the makefile would normally look.
The INC_PREFIX parameter is used to change the start directory
for all built-in include searches. This parameter contains
a space-separated string of -I directives. Quotes are needed if
any whitespace is used.
Example USER_INC="-I$HOME/xcompile/inc -I$HOME/platform/include"
USER_LIB=string: specify some library search directives
to be added to the link command for all executable
programs. This is often used when cross-compiling and
libraries are needed from multiple locations.
This parameter contains a space-separated string of
-L directives. Quotes are needed if any whitespace is used.
Example USER_LIB=-L$HOME/xcompile/lib
WEB_DIR=<dirspec>: Use the specified <dirspec> as directory
when installing the yang-api and/or restconf programs directly
into a WEB server sub-directory (non-production build)
Default is '$(DESTDIR)/var/www/yang-api'.
WEB_GROUP=<name>: Use the specified <name> as the group name
when installing the yang-api and/or restconf programs directly
into a WEB server sub-directory (non-production build)
Default is 'www-data'.
WEB_USER=<name>: Use the specified <name> as the user name
when installing the yang-api and/or restconf programs directly
into a WEB server sub-directory (non-production build)
Default is 'www-data'.
WITH_CALLHOME=1: build the IETF Call-Home reverse connection support
Default is not to add this code. Included with EVERYTHING=1.
Parts of Call-home may be patented by Juniper, Inc.
WITH_CLI=1: build the netconfd-pro server with the CLI
protocol included. Default is not to add this code
WITH_COAP=1: build the netconfd-pro server with the CoAP
protocol included. Default is not to add this code
This option is obsolete. CoAP over RESTCONF is obsolete
and NOT SUPPORTED. DO NOT USE!
WITH_CURL=1: build the netconfd-pro server with libcurl
support included. Default is not to add this code
WITH_IETF_INTERFACES=1: build the ietf-interfaces SIL code
for the netconfd-pro server. Will also include the IF-MIB
module if WITH_SNMP=1 is used as well. Default is to build
this module in package builds, but not other builds
WITH_GDB=1: add -ggdb3 to CFALGS even if DEBUG not set
Default is not to add this flag if DEBUG=1 not set
WITH_GET2_TEST=1: build the libget2-test library
enable the SIL-SA library for the get2-test module
The server must be started with --module=get2-test
and the sil-sa-app must be run for the distributed
operational data test to work
WITH_GET3_TEST=1: build the libget3-test library
enable the SIL-SA library for the get3-test module
The server must be started with --module=get3-test
and the sil-sa-app must be run for the distributed
operational data test to work
WITH_GNMI=1: build the YP-gNMI protocol
Must also use WITH_YCONTROL=1 and WITH_RESTCONF=1
Will not work unless the YP-gNMI code is present
WITH_GRPC=1: build the netconfd-pro server with the
YP-gRPC protocol included. Default is not to add this code.
WITH_HOOKS_TEST=1: build the libhooks-test directory
to install the SIL code for the hooks-test YANG module
Not supported if STATIC=1 is used
WITH_HOOKS_TEST_SILSA=1: build the libhooks-test-silsa directory
to install the SIL-SA code for the hooks-test-silsa YANG module.
The server must be started with --module=hooks-test-silsa
and the sil-sa-app must be run for the distributed
Hook callbacks test to work.
WITH_LIB_SHOW=1: add the libshow directory to the build
This builds the example libyp_show.so library.
Normally off in regular builds and always on in package builds.
WITH_LIB_SYSTEM=1: add the libsystem directory to the build
This builds the example yp-system directory.
Normally off in regular builds and always on in package builds.
WITH_OPENSSL=1: build the netconfd-pro server with OpenSSL library
support for NETCONF over TLS protocol. Default is not to add this
code.
WITH_RESTCONF=1: build the netconfd-pro server with the RESTCONF
protocol included. Default is not to add this code. If set
will load ietf-restconf-monitoring module and enable SIL
library for this module.
WITH_SIL_ERROR=1: add the sil-error directory to the build
This allows SIL errors to be easily generated during
the specified SIL callback phase for different data node types.
Used for developer testing to force corner-case transaction
code to be invoked.
WITH_SNMP=1: build the SNMP server protocol support.
Requires that WITH_RESTCONF=1 also be used in the make commands.
WITH_SUPPORT_SAVE=1: build the yumawork-support-save module
into the server. Used to add <get-support-save> operation
does not cause any server problems.
WITH_SYSTEST_SIL=1: build the test SIL libraries in the systest-sil
directory. Used for regression testing to make sure code stub SIL
does not cause any server problems. Ignored if PACKAGE_BUILD=1
is also used.
WITH_TEMPLATES=1: build the server code for the yumaworks-templates
module, to support configuration templates.
WITH_YANG11=1: Allow YANG 1.1 code to be enabled; Deprecated.
This flag MUST be set to 1 for the 16.10 release train.
This flag MUST NOT be set for the 14.04 or 15.10 release trains.
This flag is forced on starting in 16.10 and later.
WITH_YANGAPI=1: build the netconfd-pro server with the YANG-API
protocol included. Default is not to add this code
This protocol is deprecated. Use WITH_RESTCONF instead.
WITH_YANG_HASH=1: build the libdict module and add support
for fast lookup via YANG Hash object dictionary (Experimental)
WITH_YANG_PUSH=1: build the YANG-PUSH functionality in the server
for Push Telemetry support
WITH_YANGMAP=1: build the agt_yangmap functionality
for YANG model mapping feature.
WITH_YCONTROL=1: build the netconfd-pro server with the YumaPro
Control Protocol sub-system, plus ycontrol and sil-sa libraries.
Used for distributed server instrumentation.
WITH_YP_HA=1: build the YP-HA server redundancy protocol support
Requires that WITH_YCONTROL=1 also be used in the make commands.
WITH_YUMA_ARP=1: build the libyuma-arp directory
to install the SIL code for the yuma-arp YANG module.
WITH_YUMA_INTERFACES=1: build the libyuma-interfaces directory
to install the SIL code for the yuma-interfaces YANG module.
WITH_YUMA_NACM=1: build the agt_acm_nacm code and enable it
in the agt_acm module. This module is obsolete and not
supported at all. Do not use!
WITH_YUMA_PROC=1: build the libyuma-proc directory
to install the SIL code for the yuma-proc YANG module.
XCODE=<path>: specify the location of XCode usr/include directory
Only relevant if MAC=1 also set. Default:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/
Developer/SDKs/MacOSX10.11.sdk/usr/include
YP_SYSROOT=<path-string> : specify the --sysroot parameter for the
compiler and linker. The poath cannot have any whitespace in it.
Example:
YP_SYSROOT=/opt/SDK/sysroots/aarch64-xilinx-linux
Added to CFLAGS and CXXFLAGS:
--sysroot=/opt/SDK/sysroots/aarch64-xilinx-linux
To build all default components (shared libs) on Linux, this will build
all default components and install it in the default locations:
- make [FLAGS]
- [sudo] make [FLAGS] install
For example, to build all default components (shared libs) on Fedora,
64-bit:
- make LIB64=1
- [sudo] make LIB64=1 install
For example, to build all default components (shared libs)
except /usr/lib/yuma/libtoaster.so
- make NOTOASTER=1
- [sudo] make NOTOASTER=1 install
External file dependencies (for netconfd, optional):
- /etc/services
- /etc/ssh/sshd_config
- /etc/apache2/sites-available/yang-api.conf
- /etc/apache2/sites-available/restconf.conf
- a2ensite yang-api
- a2ensite restconf
- a2enmod fcgi
- SELinux config to allow access to port 830
Default Installed Programs:
- /usr/bin/db-api-app [WITH_DB_API]
- /usr/bin/yangcli-pro
- /usr/bin/yangdump-pro
- /usr/bin/yangdump-sdk
- /usr/bin/yangdiff-pro
- /usr/bin/ypcontrol
- /usr/bin/ypwatcher
- /usr/bin/yp-shell [WITH_CLI]
- /usr/bin/yp-ha-app [WITH_YP_HA]
- /usr/sbin/netconfd-pro
- /usr/sbin/netconf-subsystem-pro
- /usr/sbin/restconf [WITH_RESTCONF]
- /usr/sbin/yang-api [WITH_YANGAPI]
Default Installed Libraries:
- /usr/lib/libyumapro_agt.so.MM.NN
- /usr/lib/libyumapro_db-api.so.MM.NN [WITH_DB_API]
- /usr/lib/libyumapro_mgr.so.MM.NN
- /usr/lib/libyumapro_ncx.so.MM.NN
- /usr/lib/libyumapro_sil-sa.so.MM.NN [WITH_SIL_SA]
- /usr/lib/libyumapro_ycli.so.MM.NN
- /usr/lib/libyumapro_ycontrol.so.MM.NN [WITH_YCONTROL]
- /usr/lib/yumapro/libtoaster.so
- /usr/lib/yumapro/libyp_system.so
- /usr/lib/yumapro/libsil-error.so
Default Installed Libraries if LIB64=1:
- /usr/lib64/...
Default Installed Additional Files:
/usr/share/doc/yumapro/* -- user documentation
/etc/yumapro/* -- sample application config files
/usr/share/yumapro/* -- root of all YumaPro static data files
/usr/share/yumapro/modules/* -- root of default installed YANG modules
/usr/man/man1/* -- man page files installed here
User-Specific Files
$HOME/.yumapro -- yangcli-pro and netconfd-pro files
YumaPro Package Variants:
# the docs are no longer split into several bundles for installation
# Instead, 1 bundle for RPM and 1 for Debian are produced
#
# yumapro-doc
#
# BINARY PACKAGES
#
# yumapro-sdk ==> PACKAGE=DEVELOPER
# yumapro-pthreads ==> PACKAGE=DEVELOPER PTHREADS=1
# yangcli-pro ==> PACKAGE=CLIENT
#
# NO LONGER USED
#
# yumapro ==> PACKAGE=USER
# yumapro ==> PACKAGE=SERVER
#