Repository files navigation

bmclib v2 is a library to abstract interacting with baseboard management controllers.

• Redfish
• IPMItool
• Intel AMT
• Asrockrack
• RPC

go get github.com/bmc-toolbox/bmclib/v2

import (  bmclib"github.com/bmc-toolbox/bmclib/v2")

The snippet below connects to a BMC and retrieves the device hardware, firmware inventory.

import (  bmclib"github.com/bmc-toolbox/bmclib/v2")// setup loggerl:=logrus.New()l.Level=logrus.DebugLevellogger:=logrusr.New(l)clientOpts:= []bmclib.Option{bmclib.WithLogger(logger)}// init clientclient:=bmclib.NewClient(*host,"admin","hunter2",clientOpts...)// open BMC sessionerr:=client.Open(ctx)iferr!=nil {log.Fatal(err,"bmc login failed")    }deferclient.Close(ctx)// retrieve inventory datainventory,err:=client.Inventory(ctx)iferr!=nil {l.Error(err)    }b,err:=json.MarshalIndent(inventory,"","  ")iferr!=nil {l.Error(err)    }fmt.Println(string(b))

More sample code can be found inexamples

bmclib performs queries on BMCs usingmultipledrivers,thesedrivers are the various services exposed by a BMC -redfishIPMISSH andvendor API which is basically a custom vendor API endpoint.

The bmclib client determines which driver to use for an action likePower cycle orCreate userbased on its availability or through a compatibility test (when enabled).

When querying multiple BMCs through bmclib its often useful to to limit the BMCs anddrivers that bmclib will attempt to use to connect, the options to limit or filterout BMCs are described below,

Query just using theredfish endpoint.

cl:=bmclib.NewClient("192.168.1.1","admin","hunter2")cl.Registry.Drivers=cl.Registry.Using("redfish")

Query using theredfish endpoint and fall back toIPMI

client:=bmclib.NewClient("192.168.1.1","admin","hunter2")// overwrite registered drivers by appending Redfish, IPMI drivers in orderdrivers:=append(registrar.Drivers{},bmcClient.Registry.Using("redfish")...)drivers=append(drivers,bmcClient.Registry.Using("ipmi")...)client.Registry.Drivers=driver

Filter drivers to query based on compatibility, this will attempt to check if the driver iscompatibleideally, this method should be invoked when the client is ready to perform a BMC action.

client:=bmclib.NewClient("192.168.1.1","admin","hunter2")client.Registry.Drivers=cl.Registry.FilterForCompatible(ctx)

Ignore the Redfish endpoint completely on BMCs running a specific Redfish version.

Note: this version should match the one returned throughcurl -k "https://<BMC IP>/redfish/v1" | jq .RedfishVersion

opt:=bmclib.WithRedfishVersionsNotCompatible([]string{"1.5.0"})client:=bmclib.NewClient("192.168.1.1","admin","hunter2",opt...)cl.Registry.Drivers=cl.Registry.FilterForCompatible(ctx)

bmclib can be configured to apply timeouts to BMC interactions. The following options are available.

Total max timeout only - The total time bmclib will wait for all BMC interactions to complete. This is specified using a singlecontext.WithTimeout orcontext.WithDeadline that is passed to all method call. With this option, the per provider; per interaction timeout is calculated by the total max timeout divided by the number of providers (currently there are 4 providers).

cl:=bmclib.NewClient(host,user,pass,bmclib.WithLogger(log))ctx,cancel:=context.WithTimeout(context.Background(),30*time.Second)defercancel()iferr=cl.Open(ctx);err!=nil {return(err)}defercl.Close(ctx)state,err:=cl.GetPowerState(ctx)

Total max timeout and a per provider; per interaction timeout - The total time bmclib will wait for all BMC interactions to complete. This is specified using a singlecontext.WithTimeout orcontext.WithDeadline that is passed to all method call. This is honored above all timeouts. The per provider; per interaction timeout is specified usingbmclib.WithPerProviderTimeout in the Client constructor.

cl:=bmclib.NewClient(host,user,pass,bmclib.WithLogger(log),bmclib.WithPerProviderTimeout(15*time.Second))ctx,cancel:=context.WithTimeout(context.Background(),60*time.Second)defercancel()iferr=cl.Open(ctx);err!=nil {return(err)}defercl.Close(ctx)state,err:=cl.GetPowerState(ctx)

Per provider; per interaction timeout. No total max timeout - The time bmclib will wait for a specific provider to complete. This is specified usingbmclib.WithPerProviderTimeout in the Client constructor.

cl:=bmclib.NewClient(host,user,pass,bmclib.WithLogger(log),bmclib.WithPerProviderTimeout(15*time.Second))ctx:=context.Background()iferr=cl.Open(ctx);err!=nil {return(err)}defercl.Close(ctx)state,err:=cl.GetPowerState(ctx)

Default timeout - If no timeout is specified with a context or withbmclib.WithPerProviderTimeout the default is used. 30 seconds per provider; per interaction.

cl:=bmclib.NewClient(host,user,pass,bmclib.WithLogger(log))ctx:=context.Background()iferr=cl.Open(ctx);err!=nil {return(err)}defercl.Close(ctx)state,err:=cl.GetPowerState(ctx)

Thebmclib.Client can be configured to filter BMC calls based on a few different criteria. Filtering modifies the order and/or the number of providers for BMC calls. This filtering can be permanent or on a one-time basis.

All providers are stored in a registry (seeClient.Registry) and the default order for providers in the registry isipmitool,asrockrack,gofish,IntelAMT. The default order is definedhere.

Permanent filtering modifies the order and/or the number of providers for BMC calls for all client methods (for example:Open,SetPowerState, etc) calls.

cl:=bmclib.NewClient(host,user,pass)// This will modify the order for all subsequent BMC callscl.Registry.Drivers=cl.Registry.PreferDriver("gofish")iferr:=cl.Open(ctx);err!=nil {return(err)}

The following permanent filters are available:

• cl.Registry.PreferDriver("gofish") - This moves thegofish provider to be the first provider in the registry.
• cl.Registry.Supports(providers.FeaturePowerSet) - This removes any provider from the registry that does not support the setting the power state.
• cl.Registry.Using("redfish") - This removes any provider from the registry that does not support theredfish protocol.
• cl.Registry.For("gofish") - This removes any provider from the registry that is not thegofish provider.
• cl.Registry.PreferProtocol("redfish") - This moves any provider that implements theredfish protocol to the beginning of the registry.

One-time filtering modifies the order and/or the number of providers for BMC calls only for a single method call.

cl:=bmclib.NewClient(host,user,pass)// This will modify the order for only this BMC calliferr:=cl.PreferProvider("gofish").Open(ctx);err!=nil {return(err)}

The following one-time filters are available:

• cl.PreferProtocol("gofish").GetPowerState(ctx) - This moves thegofish provider to be the first provider in the registry.
• cl.Supports(providers.FeaturePowerSet).GetPowerState(ctx) - This removes any provider from the registry that does not support the setting the power state.
• cl.Using("redfish").GetPowerState(ctx) - This removes any provider from the registry that does not support theredfish protocol.
• cl.For("gofish").GetPowerState(ctx) - This removes any provider from the registry that is not thegofish provider.
• cl.PreferProtocol("redfish").GetPowerState(ctx) - This moves any provider that implements theredfish protocol to the beginning of the registry.

To collect trace telemetry, set theWithTraceProvider() option on the clientwhich results in trace spans being collected for each client method.

cl:=bmclib.NewClient(host,user,pass,bmclib.WithLogger(log),bmclib.WithTracerProvider(otel.GetTracerProvider()),      )

The current bmclib version isv2 and is being developed on themain branch.

The previous bmclib version is in maintenance mode and can be found herev1.

As a library we will only bump the version of Go in thego.mod file when there are required dependencies in bmclib that necessitatea version bump. When consuming bmclib in your project, we recommend always building with the latest Go version but thisshould be in your hands as a user as much as possible.

bmclib v2 interfaces with Redfish on BMCs through the Gofish libraryhttps://github.com/stmcginnis/gofish

bmclib was originally developed forBooking.com. With approval fromBooking.com,the code and specification were generalized and published as Open Source on github, for which the authors would like to express their gratitude.

• Joel Rebello
• Jacob Weinstock