RELEASE: cordial v1.5.0

Products Geneos
, ,
1

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