Install and Configure FSOC

Install fsoc

Prebuilt binaries of fsoc are published for each release. You can use the following sections to install the latest binary for the most common platforms.

Note: If you prefer to build fsoc from source code instead, see github.com/cisco-open/fsoc.

Linux or Windows with WSL

curl -fSL -o fsoc "https://github.com/cisco-open/fsoc/releases/latest/download/fsoc-linux-amd64"
chmod +x fsoc
sudo mv fsoc /usr/local/bin

Mac OS using brew (any CPU)

If you use brew:

brew tap cisco-open/tap
brew install fsoc

Mac OS with Intel CPU

curl -fSL -o fsoc "https://github.com/cisco-open/fsoc/releases/latest/download/fsoc-darwin-amd64"
chmod +x fsoc
sudo mv fsoc /usr/local/bin

Mac OS with M1/M2 CPU

curl -fSL -o fsoc "https://github.com/cisco-open/fsoc/releases/latest/download/fsoc-darwin-arm64"
chmod +x fsoc
sudo mv fsoc /usr/local/bin

Windows (Native)

If you want to run fsoc in the Windows Subsystem for Linux (WSL), use the Linux or Windows with WSL instructions above.

To install fsoc as a native application for Windows, follow these steps:

1. Download the latest release. If you have curl installed, you can run the following command in cmd.exe or Powershell: curl -fSL -o fsoc.exe "https://github.com/cisco-open/fsoc/releases/latest/download/fsoc-windows-amd64.exe"
2. Append or prepend the fsoc binary folder to your PATH environment variable.
3. Check that you have the latest version of fsoc by running the fsoc version command.

Verify Your Installation

To verify that you've installed fsoc correctly, try the fsoc version command, as shown:

fsoc version

Sample output:

fsoc version 0.55.0

If fsoc shows its version (the actual number may differ from the one shown above), then you've installed fsoc succesfully.

Add Command Autocompletion

This is an optional step that helps complete command names and flags faster by using tab autocompletion. The setup varies depending on what shell you use.

To add autocompletion in bash, run:

source <(fsoc completion bash)

For other shells, check out the completion help by running the following command:

fsoc help completion

Configure Access

fsoc recognizes that developers often work with multiple different environments all at the same time. To support this, fsoc supports the notions of contexts and config files. These concepts should be familiar to those using kubectl and/or AWS CLI (except they are called profiles in the AWS CLI). A config file can contain multiple contexts and one of them is selected as current. There is a default config file (~/.fsoc) and a default context within any file (default); a different config file and context can be specified with command line flags and/or environment variables.

For authentication, fsoc supports multiple login types:

1. OAuth (single sign on)
2. Service Principal
3. Agent Principal
4. JWT Token

The following sections specify how to configure fsoc for each login type:

OAuth (Recommended For Interactive Use)

The key advantage of using OAuth (SSO) login is that it uses the same user name and password credentials as the browser-based user interface. This is the easiest way to use fsoc interactively.

To configure FSOC for OAuth login, run the following command (replace MYTENANT with your Tenant's URL):

fsoc config set auth=oauth url=https://MYTENANT.observe.appdynamics.com
fsoc login

The first time you run the login command, fsoc will open a browser window and guide you through the login process. Once the browser-based login completes successfully, you can close the browser window and return to the command line.

Here is what you should see:

Login completed successfully.

If you see an error message instead, you may have to update the configuration.

Note: If you change the authentication method after successfully logging in, or want to change the Tenant, you may need to remove any tokens from the config file.

Service Principal (Recommended For Continuous Integration and Scripts)

The key advantage of using a service principal is that it's a one-time setup: once you configure a context with a service principal, all logins are automatically performed by fsoc (including automatically refreshing the access token when needed). This is most useful when running automated processes where there isn't a human user available to authenticate interactively.

Before using this method, you need to obtain a service principal for your desired Tenant and user. The service principal is stored in a JSON file and you will need this file. You may need your Tenant's administrator to obtain the service principal's credentials.

You can then configure fsoc for this method:

fsoc config set auth=service-principal secret-file=PATH-TO-SERVICE-PRINCIPAL-FILE.json
fsoc login

Here is what you should see:

Login completed successfully.

If you see an error message instead, you may have to update the configuration.

Note:

1. The service principal file is used by reference, so it is important to keep it in the same place and accessible when running commands with fsoc.
2. fsoc will update the config file whenever it gets an updated token using the service principal. It will add a token field to the context and manage this field automatically.
3. If you change the authentication method after successfully logging in, or want to change the Tenant, you may need to remove any tokens from the config file.

Agent Principal (Mandatory for fsoc melt Commands)

Authenticating with an agent principal is helpful for vendors developing solutions with their own agents.

To log in with an agent principal:

1. Download the agent principal credentials as a YAML file from the user interface:
   1. Go to Configure --> Kubernetes and APM (just under Cloud Connections).
   2. In Credential set name, enter a useful name for the credential set.
   3. In Kubernetes cluster name, enter an arbitrary name or "none".
   4. Click Generate file.
   5. Note that there may be two different files shown: operators-values.yaml and collectors-values.yaml. Please use the latter, collectors-values.yaml (the one that has a appdynamics-otel-collector key at the top level).
2. Run the following command:

fsoc config set auth=agent-principal secret-file PATH-TO-AGENT-PRINCIPAL-FILE.yaml --profile agent-test
fsoc login --profile agent-test -v

JWT Token

Logging in with a JWT token is a temporary login method. It can use authentication tokens obtained throuh any type of authentication. It is useful for a quick, temporary access. Obtaining the JWT token is beyond of scope for this document.

To log in with a JWT token:

fsoc config set auth=jwt url=https://TENANT-URL tenant=TENANT-ID token="TOKEN"

Note: Tokens are valid for a short time after they are generated. Once the token expires, you will need to re-run the configuration command with a new token. To do this for an existing context, you need to specify only the new token; there is no need to repeat the other flags:

fsoc config set token="NEW-TOKEN-VALUE"

When using a JWT token, there is no "login" process, as the authentication has already completed. You can simply start executing commands.