gofish

Example_conditionalReload shows schemas.Reload, the general form of a conditional GET where the caller supplies the request headers directly. Use it when you cache ETags outside the object, or when a vendor requires an unquoted ETag in If-None-Match. schemas.Refresh is the convenience wrapper over this.

package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	chassis, err := c.Service.Chassis()
	if err != nil || len(chassis) == 0 {
		log.Print(err)
		return
	}

	power, err := chassis[0].Power()
	if err != nil {
		log.Print(err)
		return
	}

	power, err = schemas.Reload(power, map[string]string{"If-None-Match": power.GetETag()})
	if errors.Is(err, schemas.ErrNotModified) {
		fmt.Println("power metrics unchanged")
		return
	}
	if err != nil {
		log.Print(err)
		return
	}

	fmt.Printf("refreshed power resource: %s\n", power.Name)
}

Output:

Example_firmwareInventory shows how to list all firmware components reported by the UpdateService, which is useful for auditing installed firmware versions across the managed system.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	updateService, err := c.Service.UpdateService()
	if err != nil {
		log.Print(err)
		return
	}

	inventory, err := updateService.FirmwareInventory()
	if err != nil {
		log.Print(err)
		return
	}

	for _, item := range inventory {
		fmt.Printf("%-40s  version=%-20s  updateable=%v\n",
			item.Name, item.Version, item.Updateable)
	}
}

Output:

Example_firmwareUpdate demonstrates a simple firmware update using an image URI. The update is submitted to the service and a task monitor is returned for polling completion status.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	updateService, err := c.Service.UpdateService()
	if err != nil {
		log.Print(err)
		return
	}

	taskInfo, err := updateService.SimpleUpdate(&schemas.UpdateServiceSimpleUpdateParameters{
		ImageURI:         "https://firmware-server/bmc-firmware-2.0.bin",
		TransferProtocol: schemas.HTTPSTransferProtocolType,
	})
	if err != nil {
		log.Print(err)
		return
	}

	if taskInfo != nil {
		fmt.Printf("Update task submitted: %s\n", taskInfo.TaskMonitor)
	}
}

Output:

Example_mountVirtualMedia demonstrates how to mount a remote ISO image as virtual media on a manager, enabling virtual CD/DVD boot without physical media.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	managers, err := c.Service.Managers()
	if err != nil {
		log.Print(err)
		return
	}

	for _, mgr := range managers {
		virtualMedia, err := mgr.VirtualMedia()
		if err != nil {
			continue
		}

		for _, vm := range virtualMedia {
			// Find the CD/DVD slot.
			if vm.MediaTypes == nil {
				continue
			}
			for _, mt := range vm.MediaTypes {
				if mt != schemas.CDVirtualMediaType && mt != schemas.DVDVirtualMediaType {
					continue
				}

				_, err := vm.InsertMedia(&schemas.VirtualMediaInsertMediaParameters{
					Image:                "https://file-server/os-installer.iso",
					TransferProtocolType: gofish.ToRef(schemas.HTTPSTransferProtocolType),
					Inserted:             gofish.ToRef(true),
					WriteProtected:       gofish.ToRef(true),
				})
				if err != nil {
					log.Printf("error inserting media: %v", err)
					continue
				}

				fmt.Printf("Mounted ISO on %s\n", vm.Name)
			}
		}
	}
}

Output:

Example_pollThermalConditionally shows how to poll a resource efficiently with a conditional GET. schemas.Refresh re-fetches the object using its own ETag as If-None-Match; when the service reports no change it returns schemas.ErrNotModified and the existing object stays valid, avoiding the JSON parse and most of the bytes on the wire. This is the intended pattern for polling fleets of BMCs for resources that change infrequently.

package main

import (
	"errors"
	"fmt"
	"log"
	"time"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	chassis, err := c.Service.Chassis()
	if err != nil || len(chassis) == 0 {
		log.Print(err)
		return
	}

	// Initial fetch captures the resource and its ETag.
	thermal, err := chassis[0].Thermal()
	if err != nil {
		log.Print(err)
		return
	}

	// Poll on an interval; only re-parse when the BMC reports a change.
	for range time.Tick(30 * time.Second) {
		refreshed, err := schemas.Refresh(thermal)
		switch {
		case errors.Is(err, schemas.ErrNotModified):
			continue // unchanged since last poll; keep using the cached object
		case err != nil:
			log.Printf("error refreshing thermal: %v", err)
			continue
		}

		thermal = refreshed
		for i := range thermal.Temperatures {
			if temp := &thermal.Temperatures[i]; temp.ReadingCelsius != nil {
				fmt.Printf("%s: %.1f °C\n", temp.Name, *temp.ReadingCelsius)
			}
		}
	}
}

Output:

Example_queryManagers shows how to list BMC/management controller details, such as firmware version and network protocol configuration.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	managers, err := c.Service.Managers()
	if err != nil {
		log.Print(err)
		return
	}

	for _, mgr := range managers {
		fmt.Printf("Manager: %s  type=%s  firmware=%s\n",
			mgr.Name, mgr.ManagerType, mgr.FirmwareVersion)

		netProto, err := mgr.NetworkProtocol()
		if err != nil {
			continue
		}
		fmt.Printf("  Hostname: %s\n", netProto.HostName)
	}
}

Output:

Example_querySystemInventory demonstrates how to retrieve processor and memory information from all systems registered with the service.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	systems, err := c.Service.Systems()
	if err != nil {
		log.Print(err)
		return
	}

	for _, system := range systems {
		fmt.Printf("System: %s\n", system.Name)

		processors, err := system.Processors()
		if err != nil {
			log.Printf("error getting processors: %v", err)
		}
		for _, p := range processors {
			fmt.Printf("  CPU: %s %s\n", p.Manufacturer, p.Model)
			fmt.Printf("    Cores: %d  Threads: %d\n",
				gofish.Deref(p.TotalCores), gofish.Deref(p.TotalThreads))
			fmt.Printf("    Max speed: %d MHz\n", gofish.Deref(p.MaxSpeedMHz))
		}

		memory, err := system.Memory()
		if err != nil {
			log.Printf("error getting memory: %v", err)
		}
		for _, dimm := range memory {
			fmt.Printf("  DIMM: %s  %d MiB  %d MHz\n",
				dimm.Name,
				gofish.Deref(dimm.CapacityMiB),
				gofish.Deref(dimm.OperatingSpeedMhz))
		}
	}
}

Output:

Example_queryThermal shows how to read temperature sensor and fan speed readings from all chassis managed by the service.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	chassis, err := c.Service.Chassis()
	if err != nil {
		log.Print(err)
		return
	}

	for _, ch := range chassis {
		thermal, err := ch.Thermal()
		if err != nil {
			log.Printf("error getting thermal for chassis %s: %v", ch.Name, err)
			continue
		}

		fmt.Printf("Chassis: %s\n", ch.Name)

		for i := range thermal.Temperatures {
			temp := &thermal.Temperatures[i]
			if temp.ReadingCelsius == nil {
				continue
			}
			fmt.Printf("  Temp: %-30s  %.1f °C\n", temp.Name, *temp.ReadingCelsius)
		}

		for i := range thermal.Fans {
			fan := &thermal.Fans[i]
			if fan.Reading == nil {
				continue
			}
			fmt.Printf("  Fan:  %-30s  %d %s\n", fan.Name, *fan.Reading, fan.ReadingUnits)
		}
	}
}

Output:

Example_readEventLog shows how to read entries from the system event log via the Manager's LogService. This is useful for diagnostics and auditing.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	managers, err := c.Service.Managers()
	if err != nil {
		log.Print(err)
		return
	}

	for _, mgr := range managers {
		logServices, err := mgr.LogServices()
		if err != nil {
			continue
		}

		for _, ls := range logServices {
			entries, err := ls.Entries()
			if err != nil {
				continue
			}

			fmt.Printf("Log: %s\n", ls.Name)
			for _, entry := range entries {
				fmt.Printf("  [%s] %s: %s\n",
					entry.Severity, entry.Created, entry.Message)
			}
		}
	}
}

Output:

Example_subscribeEvents shows how to register a webhook endpoint to receive Redfish event notifications. The returned subscription URI can be used later to modify or delete the subscription.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	eventService, err := c.Service.EventService()
	if err != nil {
		log.Print(err)
		return
	}

	// Subscribe using registry prefixes (Redfish v1.5+).
	subscriptionURI, err := eventService.CreateEventSubscriptionInstance(
		"https://my-event-receiver/redfish/events", // destination
		[]string{"Alert", "ResourceEvent"},         // registry prefixes
		[]string{},                                 // all resource types
		nil,                                        // no custom HTTP headers
		schemas.RedfishEventDestinationProtocol,
		"my-monitoring-service", // client-supplied context string
		schemas.RetryForeverDeliveryRetryPolicy,
		nil, // no OEM data
	)
	if err != nil {
		log.Print(err)
		return
	}

	fmt.Printf("Subscription created: %s\n", subscriptionURI)

	// Delete the subscription when no longer needed.
	if err := eventService.DeleteEventSubscription(subscriptionURI); err != nil {
		log.Print(err)
	}
}

Output:

Example_updateBiosAttributes shows how to read and modify BIOS settings. Changes are applied at the next reboot unless an immediate apply time is specified.

package main

import (
	"fmt"
	"log"

	"github.com/stmcginnis/gofish"
	"github.com/stmcginnis/gofish/schemas"
)

func main() {
	c, err := gofish.Connect(gofish.ClientConfig{
		Endpoint: "https://bmc-ip",
		Username: "my-username",
		Password: "my-password",
		Insecure: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Logout()

	systems, err := c.Service.Systems()
	if err != nil {
		log.Print(err)
		return
	}

	for _, system := range systems {
		bios, err := system.Bios()
		if err != nil {
			log.Printf("error getting BIOS for %s: %v", system.Name, err)
			continue
		}

		// Print current attribute values.
		for name, value := range bios.Attributes {
			fmt.Printf("  %s = %v\n", name, value)
		}

		// Update an attribute to take effect on next reboot.
		if err := bios.UpdateBiosAttributesApplyAt(
			schemas.SettingsAttributes{"NumaGroupSizeOpt": "Flat"},
			schemas.OnResetSettingsApplyTime,
		); err != nil {
			log.Printf("error updating BIOS: %v", err)
		}
	}
}

Output: