Deepfactor CLI Reference

 

dfctl is Deepfactor's command line interface. This can be downloaded from Deepfactor's public package repositories. It is installed in the /usr/bin/dfctl location. Along with dfctl, another file, libdf.so is also installed at /opt/deepfactor/lib/libdf.so

Table of Contents

DF CLI Docker Init

The DF CLI for launching docker images with DF instrumentation uses Docker Volume. This volume contains the runtime libs required to run the application with DF. This volume is mounted while launching the application. The volume must be initialized before it can be used to launch application images with DF instrumentation.

  • Users must execute the following command to initialize the Docker volume.

curl https://repo.deepfactor.io/install-dfctl.sh | sh -
  • Install specific versions of the Deepfactor runtime:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s -- --version 2.2.0-1200
  • Install dfctl without initializing docker volumes:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s -- --no-docker-volume
  • Install dfctl with a specific runtime image:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s - --dfrt-image 241761893560.dkr.ecr.us-east-2.amazonaws.com/df/runtime --version 2.2.0-1200

App Launcher

Deepfactor's dfctl run command now supports two formats to run an application directly or a container via --docker-run.

dfctl app launcher:

dfctl run 
[-v] [-f] [-t tag] -a "application name" -c "component name"
[-p "alert policy"] [--version component-version]
[--env "environment name"] [--entrypoint-libc "musl"|"glibc" ]
[--disable-stack-traces] [--enable-method-tracing]
--cmd command with arguments

dfctl docker app launcher:

dfctl run 
[-v] [-f] [-t tag] -a "application name" [-c "component name"]
[-p "alert policy"] [--version component-version]
[--env "environment name"] [--entrypoint-libc "musl"|"glibc" ]
[--disable-stack-traces] [--enable-method-tracing]
--docker-run [docker run CLI arguments] --image [command arguments]

Command to register application in portal :

dfctl register 
[-v] [-f] [-t tag] -a "application name" [-c "component name"]
[-p "alert policy"] [--version component-version]
[--env "environment name"] [-n "image name"] [-i "image id"]
[--disable-stack-traces] [--enable-method-tracing] [-o output]
-a or --application (required) specify the name of your application. If an application with this name does not already exist on your Deepfactor Portal, it will be created.

-c or --component (optional) specify the component name. Default is the image name without tag.
--version (optional) specify the version of the component you are currently running. You can filter insights based on this version number. If not specified, the md5sum or the image Tag will be used.  If an image has no tag, then the image Id will be used.
-p or --policy (optional) specify the alert policy for this component. This policy will be used to raise alerts for all active and future instances of this component.
--cmd (required) specify the full command along with arguments you use to launch your component. Please note this should be the last argument of dfctl run command.

--docker-run (required) If you are running a docker container, please specify the full docker run command along with the arguments you use to run your container. Please note this should be the last argument of dfctl run command.

Other options

-v (optional) can be used to run the tool in verbose mode.
-l or --lang (deprecated) Deepfactor can enhance alerts by enabling language-specific probes. If you are running a java component, please add -l "java" option to dfctl run command. For other programming languages, there is no need to add this option.
-t or --tag (optional) specify comma-separated key value pairs to tag this instance. You can filter such instances using tags. Example: -t "key1=value1,key2=value2"
-E or --env (optional) specify the environment in which you are running your component (Ex. staging, qa etc.). You can filter insights based on the environment you specify.
Hybrid libc environments

--fail-safe or -f (optional) - In case the application cannot be instrumented by dfctl, the application deployment is not affected. An uninstrumented application is deployed, its entry is displayed in the portal. However no additional data related to application can be seen on UI (Alerts, Vulnerabilities, etc)

--entrypoint-libc (optional) "musl"|"glibc" - For containerized workloads, if the libc required by the entrypoint does not match the OS distribution libc then it can be specified with this option. You can read more about this option in the below article

Hybrid libc environments

--disable-stack-traces (optional) - Stack traces are enabled by default, this option is to disable stack traces. You can read more about this option in the below article
Language Specific Agents (LSA)

Note: Applications could see a performance impact when run with Deepfactor since stack traces are enabled by default.

--enable-method-tracing (optional) -This can be used to enhance application alerts by enabling language specific function or method tracing. You can read more about this option in the below article
Language Specific Agents (LSA)

Note: All dfctl arguments must be specified before --cmd on the command line. The argument specified with --cmd must be executable name followed by the list of arguments with which the executable must be launched.

Design

The host running dfctl and docker cli may run any supported Linux distribution (Ubuntu, Centos, etc.) and the deployed image could be of yet another supported distro and version. For example, we may have docker host running on Ubuntu while the deployed image could be Alpine.

To instrument an Alpine image from an Ubuntu or Centos based host, we will package glibc as well as muslc flavors of libdf.so in the Deepfactor-runtime package. This will be done only for rpm and deb packages. Hence, while installing the Deepfactor-runtime package on Ubuntu or Centos host, we will have libdf.so for rpm, deb or Alpine-based containers.

DFctl Run when invoked with --docker-run option will have to fingerprint the image being run to find the distro. Based on this, dfctl will copy glibc or muslc flavor of libdf.so into a directory that will be mounted into the container during launch. During this process, dfctl will call the register component API to generate manifest file. Path to this file will be used to set DF_MANIFEST environment variable while running the container image.

Container

In addition to the above technique to use to "dfctl run ... --docker-run", you can add Deepfactor to a container image or by using the Deepfactor mutating webhook. Please see the following articles.

System Service

dfctl service register 
[-v] [-f] [-t tag] -a "application name" -c "component name"
[-p "alert policy"] [--version component-version]
[--env "environment name"]
[-r] service
The command service register is primarily used for adding DF instrumentation to system service. This command modifies the service control file, sets the environment required to run the service with DF instrumentation, and restarts / starts the service is -r flag is specified.

--application or -a (required) is used to specify the application name
--component or -c (optional) is used to specify the component name.
--version (optional) can be used to register the app with a specific version string.
-v (optional) can be used to run the tool in verbose mode.
-t (optional) can be used to specify the build-time tag.
-l (optional) is used to specify the programming language of the component. It is used for multiple purposes including injecting Deepfactor’s language-specific agent into the DF instrumented component. For example, setting -l “java” will enable the collection of java specific metrics including java stack trace frames.
-p (optional) is used to specify the alert policy to be set for the DF instrumented component. The alert policy can also be set from the DF portal.
--env or -E (optional) is used to specify the deployment environment name.
-r can be used to start/restart the service with DF instrumentation.

--fail-safe or -f (optional) - In case the application cannot be instrumented by dfctl, the application deployment is not affected. An uninstrumented application is deployed, its entry is displayed in the portal. However, no additional data related to the application can be seen on UI (Alerts, Vulnerabilities, etc)

dfctl service deregister [-v] [-r] service

The command service deregister is to remove DF instrumentation for service and restore the service control file to its original state.
-v (optional) can be used to run the tool in verbose mode.
-r (optional) can be used to start/restart the service with DF instrumentation.

dfctl service list

The command service list is to list all the services that are DF instrumentation enables.

Miscellaneous

Display the current version of dfctl :

dfctl version

Display the list of policies :

dfctl policy list
 
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.