RELEASE: cordial v1.5.0

pgalbavy · 22 May 2023 13:39

I am very happy to announce the release of the latest version of cordial. Please see the release notes/ changelog below.

Change Log

Version v1.5.0

Released 2023/05/22

Please report issues via github or the ITRS Community Forum.

v1.5.0 - Highlights

This release brings numerous changes to the cordial tools, especially
the geneos utility. We have tried to improve the reliability and
usability of the utility through updated and improved documentation and
subsequent fixes and changes that arose from writing and checking that
documentation.

v1.5.0 - BREAKING CHANGES

pkg/logger:
- REMOVED. This simplistic internal logging package has been
  deprecated in favour of more mature solutions, such as
  zerolog.
tools/geneos:
- The way SAN instances handle gateway connections has been fixed to
  allow gateway represented as FDQNs or IP addresses. The old way
  resulted in a mess - viper defaults to dots (‘.’) as configuration
  item hierarchy delimiters and this caused issues. Most users with
  SANs should not notice any change, but if you see problems please
  check the san XML file and correct the gateways section as
  necessary. One way is to remove and re-set them using:
  
  geneos set san mySan -g gateway.example.com ...
  
  Running set will rewrite the configuration in the new format bu
  there is a chance that the previous configuration will continue to
  occupy settings. You may need to manually edit the instance
  configuration file san.json anyway.
- Like the above any variables defined for either SAN or Gateway
  instances used to generate XML from templates will have not worked
  in a case sensitive manner to mirror how Geneos treats variable
  names. To fix this the internal format of the variables section
  has been updated to move the variable name from the configuration
  key to a separate structure as it’s own value. Code has been added
  to automatically convert from the old format to the new when the
  configuration file is updated however there is no fix for the
  correction of variable case name being incorrect from previous
  configurations. Please review and adjust as necessary.
- Support for running instances as other user accounts or under
  sudo has been deprecated. Security is hard, and the support
  for these was poorly implemented. A better way should be coming in
  a future release.
  
  This may mean that where users has configured netprobes to run as
  different users and have previously run sudo geneos start to let
  the program do the right thing will run into issues. Please be
  careful if any of your instances run as other users and do not run
  the geneos program with sudo. There is no additional
  checking/rejection of running under sudo or any other privilege
  escalation system so this is important!

v1.5.0 - Other Changes

There has been a significant amount of refactoring and moving around
of the code-base. Most of this should not be user visible, but some
public APIs have changed. As with all major changes there may be
problems that have not been caught in testing. Please report
anything you see as either a github
issue or via the
ITRS Community Forum.

There are too many changed to list them all in detail but specific
ones worth mentioning include:
- memguard
  support for protected memory. Credentials (passwords, TLS keys and
  so on) should now be handled as Enclaves (for plaintext or private
  keys) or as LockedBuffers (for ciphertexts of sensitive data).
  
  The config package includes new methods
  for handling configuration file data as Enclaves and LockedBuffers
  to try to reduce the amount of confidential data visible in the
  process.
  
  The changes are ongoing and, in addition to adding a layer of data
  security to cordial, an added benefit is the interception of
  memory use errors etc. If you see errors, panic etc. please report
  them as a github
  issue
- A number of the previous package APIs have undergone review and
  changed as needed. In particular the
  config API has been through the wringer
  and if you have any code that relies on it from v1.4 or earlier
  then it will require changes. There are new functions, which is to
  be expected, but also some existing ones have been renamed or had
  their argument signatures changed. Please review the documentation
  to see what the methods and functions have become.
- Credentials support. There is both general purpose and
  geneos specific support for the local
  storage of credentials. Passwords and other secrets “at rest” are
  stored in Geneos AES256 format using a key file that is initial
  auto-generated. To decode these passwords you must have both the
  key file (which is by default only user readable) and the
  credentials file. There should be support for other credentials
  types, such as OAuth style client secrets and tokens, in future
  releases. The username and the domain that the credentials
  apply to are not encrypted, by design. This is however subject to
  change in a future release.
  
  Credentials currently works with a free-text domain that matches a
  destination using a “longest match wins” search, e.g. for a URL
  this may be a full or partial domain name, and for Geneos
  component authentication, e.g. the REST command API, the domain is
  in the form gateway:NAME. Others will be added later, probably
  including TLS certificates and keys as well as SSH password and
  private keys.
- Releases now include selected binaries with a semantic version
  suffix. The programs in cordial use the base name of the binary
  as a key to select which configuration files to load, so that
  renaming the binary will result in a different set of
  configuration file being used, automatically.
  
  To make life simpler, any version suffix is automatically stripped
  if, and only if, it matches the one used to build the binary. This
  means you can now download geneos-v.1.5.0 and use it without
  having to rename it (useful for initial testing of new releases).
tools/geneos:
- Extensive documentation restructuring and rewriting. This is still
  work in progress but largely complet. Built-in help text (shown
  with the help command or the --help/-h option) should now
  align much more closely with real functionality and the online
  documentation is now almost completely built from the same source.
- Addition of subsystems to group commands.
- Move aes and tls command sources to their subsystems.
- Add host and package subsystems and create aliases for the
  original commands, e.g.
  - add host becomes host add
  - install becomes package install
  - etc.
- The set user, show user etc. commands are now under single
  config subystem, e.g. geneos config set mykey=value
- The set global and related commands have been deprecated.
- The new package subsystem command pulls all Geneos release
  management into one place
- New login and logout commands to manage credentials.
- New ca3 and floating components for Collection Agent 3 and Floating
  Netprobes
tools/dv2email:
- This new utility can be run as a Geneos Action or Effect to
  capture one or more Dataviews and send as an email. The
  configuration is extensive and the layout and contents are
  completely configurable through the use of Go templates.

v1.5.0 - Bug Fixes

tools/geneos:
- Version checking of local release archives was broken because of
  overloading of a common function. This is now split and checking
  should work once again.
- Most reported issues on github have been fixed.

v1.5.0 - To Do

Documentation needs more work and refinement. The built-in help for
almost all commands is now up-to-date but the init and tls
subsystems need to be reviewed further and completed. This should be
in a patch release soon.
tools/geneos:
- Local storage of encrypted passwords for remote SSH access needs
  documenting