NAME

DOCSIS::ConfigFile - Decodes and encodes DOCSIS config files

DESCRIPTION

DOCSIS::ConfigFile is a class which provides functionality to decode and encode DOCSIS (Data over Cable Service Interface Specifications) config files.

This module is used as a layer between any human readable data and the binary structure.

The files are usually served using a TFTP server, after a cable modem or MTA (Multimedia Terminal Adapter) has recevied an IP address from a DHCP server. These files are binary encode using a variety of functions, but all the data in the file are constructed by TLVs (type-length-value) blocks. These can be nested and concatenated.

See the source code or https://thorsen.pm/docsisious for list of supported parameters.

SYNOPSIS

  use DOCSIS::ConfigFile qw(encode_docsis decode_docsis);

  $data = decode_docsis $bytes;
  $bytes = encode_docsis({
    GlobalPrivacyEnable => 1,
    MaxCPE              => 2,
    NetworkAccess       => 1,
    BaselinePrivacy     => {
      AuthTimeout       => 10,
      ReAuthTimeout     => 10,
      AuthGraceTime     => 600,
      OperTimeout       => 1,
      ReKeyTimeout      => 1,
      TEKGraceTime      => 600,
      AuthRejectTimeout => 60,
      SAMapWaitTimeout  => 1,
      SAMapMaxRetries   => 4
    },
    SnmpMibObject => [
      {oid => "1.3.6.1.4.1.1.77.1.6.1.1.6.2",    INTEGER => 1},
      {oid => "1.3.6.1.4.1.1429.77.1.6.1.1.6.2", STRING  => "bootfile.bin"}
    ],
    VendorSpecific => {id => "0x0011ee", options => [30 => "0xff", 31 => "0x00", 32 => "0x28"]}
  });

OPTIONAL MODULE

You can install the SNMP.pm module to translate between SNMP OID formats. With the module installed, you can define the SnmpMibObject like the example below, instead of using numeric OIDs:

  encode_docsis({
    SnmpMibObject => [
      {oid => "docsDevNmAccessIp.1",     IPADDRESS => "10.0.0.1"},
      {oid => "docsDevNmAccessIpMask.1", IPADDRESS => "255.255.255.255"},
    ]
  });

WEB APPLICATION

There is an example web application bundled with this distribution called "Docsisious". To run this application, you need to install Mojolicious and YAML::XS:

  $ curl -L https://cpanmin.us | perl - -M https://cpan.metacpan.org DOCSIS::ConfigFile Mojolicious;

After installing the modules above, you can run the web app like this:

  $ docsisious --listen http://*:8000;

And then open your favorite browser at http://localhost:8000. To see a live demo, you can visit https://thorsen.pm/docsisious.

FUNCTIONS

decode_docsis

  $data = decode_docsis($byte_string);
  $data = decode_docsis(\$path_to_file);

Used to decode a DOCSIS config file into a data structure. The output $data can be used as input to "encode_docsis". Note: $data will only contain array-refs if the DOCSIS parameter occur more than once.

encode_docsis

  $byte_string = encode_docsis(\%data, \%args);

Used to encode a data structure into a DOCSIS config file. Each of the keys in $data can either hold a hash- or array-ref. An array-ref is used if the same DOCSIS parameter occur multiple times. These two formats will result in the same $byte_string:

  # Only one SnmpMibObject
  encode_docsis({
    SnmpMibObject => {
      oid => "1.3.6.1.4.1.1429.77.1.6.1.1.6.2", STRING => "bootfile.bin"
    }
  })

  # Allow one or more SnmpMibObjects
  encode_docsis({
    SnmpMibObject => [
      {oid => "1.3.6.1.4.1.1429.77.1.6.1.1.6.2", STRING => "bootfile.bin"}
    ]
  })

Possible %args:

• mta_algorithm

  This argument is required when encoding MTA config files. Can be set to either empty string, "sha1" or "md5".

• shared_secret

  This argument is optional, but will be used as the shared secret used to increase security between the cable modem and CMTS.

COPYRIGHT AND LICENSE

Copyright (C) 2014-2018, Jan Henning Thorsen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CREDITS

Font Awesome

docsisious bundles Font Awesome.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org

cpanm DOCSIS::ConfigFile

perl -MCPAN -e shell
install DOCSIS::ConfigFile