MIMIC® Online Documentation

<< Previous Section    Next Section >>

MIMIC TFTP Protocol Module Guide

  1. Table of Contents

  2. Overview

    3. The MIMIC TFTP Protocol Module is an optional facility that enables client TFTP file downloads (sessions) either through MIMICView at the startup time of an agent instance, or through MIMICshell commands at both startup and running state of an agent. Each of these downloads (sessions) are identified by a unique identifier called session-id.

    MIMIC TFTP gives you control whether you want to save the downloaded data in a disk file, process it through an action script, or discard it upon transfer.

    Back to Top

  3. Installation

    4. TFTP client support is made available in MIMIC as an optional dynamically loadable module. Starting with MIMIC 10.00, you can use the Protocol Wizard to install the TFTP module. If you prefer to enable TFTP by hand, you need to do the following:

    • Use File->Terminate to stop the any running MIMIC daemon.

    • Copy the TFTP library (tftp.dll on Windows, tftp.so on Unix) from "bin/dynamic/optional" to "bin/dynamic" in the install directory.

    • Install the license keys as detailed in the instructions e-mailed to you.

    • Restart MIMIC. You should see the following type of message in the MIMICLog that confirms that the TFTP module was properly loaded : 
      INFO  - TFTP : Loaded protocol from < path-to-DLL >
INFO  - TFTP (IOS) v7.00 : Individual license #2345

    Once TFTP is loaded, any agent instance configured to support the TFTP protocol will be able to do TFTP transfers from a TFTP server.

    Back to Top

  4. Using TFTP from MIMICView

    5. If the TFTP module is enabled, then Agent->Add, Agent->Configure and Agent->Paste dialogs will display TFTP as an additional checkbox in the Advanced pane along with the SNMP protocols. On selecting the checkbox a new TFTP pane will appear.

    This TFTP configuration pane lets the user configure the parameters for a TFTP session:

    • Server

      This mandatory parameter specifies the TFTP Server IP address, either as "dot-value" notation (e.g., 192.9.200.1), or as a hostname (e.g., gambit), or fully qualified domainname (e.g., gambit.gambitcomm.com) provided that they can be resolved to an address (via /etc/hosts, Yellow Pages or DNS).

    • Port

      The TFTP client talks to the standard TFTP port 69 on the TFTP server by default. If the server is configured to use a non-standard port, you can specify it in this option.

    • Client

      This optional parameter specifies the local IP address, either as "dot-value" notation (e.g., 192.9.200.1), or as a hostname (e.g., gambit), or fully qualified domainname (e.g., gambit.gambitcomm.com) provided that they can be resolved to an address (via /etc/hosts, Yellow Pages or DNS). This address can be a previously configured IP alias, or a temporary address for the duration of the transfer. By default, if it is left empty the main address of the agent is used.

    • Source File

      This mandatory parameter specifies the file to be retrieved from the server. This is a server-dependent file path, eg. on Unix a relative path off /tftpboot.

    • Destination File

      This optional parameter specifies a file path to save the downloaded data in. The file path is relative to the directory specified in the environment variable MIMIC_TMPDIR, or /tmp/ . If the action script parameters is set below, but the destination file is not set, then its name will be auto generated. MIMIC TFTP will not allow more than one session to share the same destination filename (to prevent corruption of data).

    • Action Script

      If this optional parameter is set, then upon completion of the data transfer, either successfully or unsuccessfully, an action script will be called with the following global variables as input:

      • gCurrentAgent

      • gSessionId

      • gStatus = [ success | error | timeout | interrupted ]

      • gModeOfOperation = [ read | write ]

      • gServer

      • gServerPort

      • gSrcFile

      • gDstFile

      • gModeOfTransfer = [ ascii | bin ]

      • gTimeout

      • gRetries

      • gCache

      • gBuffer = data or error message

      • gBytes

      • gErrorCode

      • gTransferTime

      If the action script was not set then the data will be discarded.

    • Transfer Mode

      By default, the transfer mode is "ascii". Else, if you want binary data to be transferred, use the mode "raw". If you want data to be converted to a space-separated hexadecimal representation, use "binary".

    • Timeout

      This optional parameter specifies the time to wait for a response between successive retransmits in seconds. The default is 5 seconds.

    • Retries

      This optional parameter specifies the number of retransmits. The default is 5.

    • Trace

      This parameter enables tracing.

    • Blocks to cache (0 - 10)

      If this parameter is set to non zero blocks then the data will be buffered in memory. If the data grows beyond a chosen limit then the buffered data will be moved to the destination file. If no destination file name is set an auto generated temporary file name will be used as the destination file name. The subsequent write will be done on this file.

    If the mandatory parameters are supplied, the agent will automatically initiate a TFTP transfer upon starting.

    In the case of a DOCSIS CM simulation, when DHCP has completed, the TFTP protocol will take over. To configure TFTP parameters for the agent using the information received from the DHCP offer and loaded into variables above, insert the following into the start.mtcl agent startup action script: 

    # 
# configure agent for tftp, set server, filename params 
set session_id [mimic agent protocol msg TFTP session read $server $file] 
puts stderr " session_id = $session_id " 
mimic agent protocol msg TFTP $session_id set dstfile myfile_$session_id 
mimic agent protocol msg TFTP $session_id set script tftp-rfis-appndx-d-2.1.mtcl 
mimic agent protocol msg TFTP $session_id set cache 0 
# mimic agent protocol msg TFTP $session_id set mode binary 
mimic agent protocol msg TFTP $session_id start 
# mimic timer script add dhcp_timer.mtcl -1 [mimic agent assigned]

    The script referred to above, tftp-rfis-appndx-d-2.1.mtcl, is a MIMIC TFTP completion script which will run following completion of the file download of the device configuration file. It's purpose is to parse the received configuration file and set the simulated device's operating parameters accordingly.

    The tftp-rfis-appndx-d-2.1.mtcl script is available by request from Gambit, either separately or as part of the DOCSIS sample simulation. Many, but not all defined DOCSIS config file TLV's (configuration settings in Type-Length-Value format) are included in this script, along with procedures for parsing different encoding types. This file is user-editable if TLV's not defined in the script are required.

    Finally, the "timer script add" statement which is commented out at the end of the start.mtcl fragment above refers to a script which would be used to launch traps or informs following successful completion of the initialization cycle.

    Back to Top

  5. Using TFTP from MIMICShell

    6. A few new commands and some enhanced old commands can be used from the MIMICShell to use the TFTP functionality. Here is a synopsis:

    • mimic protocol msg TFTP get args

      This command lets the user gather the self-defining list of arguments required and their particulars. The parameters are detailed above. A sample exchange for this command would be: 

        mimicsh> mimic protocol msg TFTP get args
  {{server} {Server} {string} {} {optional} {}}
  {{port} {Port} {integer} {} {optional} {69}}
  {{client} {Client} {string} {} {optional} {}}
  {{srcfile} {Source File} {string} {} {optional} {}}
  {{dstfile} {Destination File} {string} {} {optional} {}}
  {{script} {Action Script} {file} {scripts {{*.mtcl {MIMIC Tcl scripts}
   {edit yes} {new yes}} {*.tcl {Tcl script files} {edit yes} {new yes}}
   {*.so {C/C++ DLL files} {edit no} {new no}}} - both} {optional} {}}
  {{mode} {Transfer Mode} {string} {} {optional} {ascii}}
  {{timeout} {Timeout (sec)} {integer} {} {optional} {5}}
  {{retries} {Retries} {integer} {} {optional} {5}}
  {{trace} {Trace} {string} {} {optional} {off}}
  {{cache} {Blocks to cache (0 - 10)} {integer} {} {optional} {4}}

    • mimic agent get protocol

      This command lets the user look at the protocols currently configured on the agent. A sample exchange for this command would be: 

        mimicsh> mimic agent get protocol
  snmpv1,snmpv2c

    • mimic agent set protocol

      This command lets the user change the protocol setting for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent set protocol snmpv1,TFTP
  mimicsh> mimic agent get protocol
  snmpv1,TFTP

    • mimic agent protocol msg TFTP get config

      This command lets the user get the current argument settings. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg TFTP get config
  {server=dmb.gambitcomm.com} {port=69} {client=} {srcfile=five-m} {dstfile=uwe123}
  {script=} {mode=ascii} {timeout=5} {retries=5} {trace=off} {cache=4}

    • mimic agent protocol msg TFTP set config [config]

      This command lets the user change the current argument settings of all TFTP sessions for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg TFTP set config {server=genesis.gambitcomm.com}

  mimicsh> mimic agent protocol msg TFTP get config
  {server=genesis.gambitcomm.com} {port=69} {client=} {srcfile=five-m} {dstfile=uwe123}
  {script=} {mode=ascii} {timeout=5} {retries=5} {trace=off} {cache=4}

    • mimic agent protocol msg TFTP get trace
      mimic agent protocol msg TFTP set trace [0 or 1]

      This command lets the user change the TFTP tracing configuration for an agent. A sample exchange would be: 

        mimicsh> mimic agent assign 1

  mimicsh> mimic agent protocol msg TFTP get trace
  0
  mimicsh>  mimic agent protocol msg TFTP set trace 1

  mimicsh> mimic agent protocol msg TFTP get trace
  1
      and the log would show: 

      INFO  - agent 9 trace enabled for TFTP
INFO  - agent 9 configured at 10.0.0.9,161.
INFO  - agent 9 loading
INFO  - agent 9 loaded device
INFO  - TFTP: starting "read" session 5 for agent 9
INFO  - TFTP [AGT=9,SES=5]: sent RRQ <file=foo.10, mode=netascii>
INFO  - TFTP [AGT=9,SES=5]: received ERROR <code=1, msg= File not found
ERROR - TFTP [AGT=9,SES=5]: 7911790
      - Error code 101: File not found

    • mimic protocol msg TFTP get stats_hdr
      mimic agent protocol msg TFTP get statistics

      Returns TFTP statistics information:

      • a list of statistic headers, and
      • current statistics values for the specified client.

      In order, the statistic values are:

      • Total number of TFTP packets sent.
      • Total number of TFTP packets received.
      • Total number of TFTP packets discarded.
      • Total number of retransmits.
      • Total number of timeouts.
      • Total number of interrupted transfers.
      • Total number of errors.
      • Total number of completed transfers.

      A sample exchange for these commands would be: 

        mimicsh> mimic protocol msg TFTP get stats_hdr
  {{pktSnt} {PktsSent}} {{pktRcvd} {PktsRcvd}} {{pktDisc} {PktsDiscarded}}
  {{rexmt} {Retransmits}} {{timeout} {TimeOuts}} {{inter} {Interrupted}}
  {{errRcvd} {Errors}} {{cmptd} {Completed}}

  mimicsh> mimic agent protocol msg TFTP get statistics
  1 0 0 0 0 0 1 0

    • mimic agent protocol msg TFTP session read server srcfile
      mimic agent protocol msg TFTP session write server srcfile

      TFTP client sessions are created by the session command by passing the mode of operation (read or write), the server address (ip address or host name) and the source file name as arguments. This command returns a non zero session-id if the session got created successfully. A sample exchange for this command would be: 

        mimicsh> set sessionid [mimic agent protocol msg TFTP session read server srcfile]
  5

or

  mimicsh> set sessionid [mimic agent protocol msg TFTP session write server srcfile]
  5

      In write mode the source file (srcfile) will be read from the simulation directory for the agent (ie. data/sim/[sim-name]). Many TFTP servers allow TFTP put (write) operation only if a file with the same name exists. If you want to write to a different file on the server, then use 

      mimic agent protocol msg TFTP $sessionid set dstfile filename

    • mimic agent protocol msg TFTP session-id get parameter

      The user can get the attribute values of the session at any time by specifying a valid session id and parameter name. The get command will fail with an error message "Invalid TFTP session id", if the session id is invalid A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg TFTP 5 get server
  genesis.gambitcomm.com
  mimicsh>  mimic agent protocol msg TFTP 5 get port
  69

    • mimic agent protocol msg TFTP session-id set parameter

      The user can set the attribute values of each session by specifying a valid session id, attribute name and the value. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg TFTP 5 set port 79

  mimicsh>  mimic agent protocol msg TFTP 5 get port
  79

      The users can set values to its attributes before the start command is issued. Any set command after start fails with an error message "TFTP session started".

      If the session id is invalid then the start command fails with an error message "Invalid TFTP session id".

    • mimic agent protocol msg TFTP session-id start

      The TFTP data transfer can be started by start command, provided all the mandatory attributes are set. A sample exchange for this command would be: 

        mimic agent protocol msg TFTP 5 start

      A start command would fail for the following reasons i) if the session is already started. ii) if the session id is not valid.

      Note: If no destination file is specified the TFTP client handles it differently for read and write. In case of write, the destination file name will be substituted by source file name. But in case of read the client would auto-generate a temporary file name and use it as destination file name.

    • mimic agent protocol msg TFTP session-id status

      Basically this command is to query the status of client session. This command return a space separated string of type:value list. This command will fail with an error message "Invalid session id" if the session id is invalid. A sample exchange for this command would be: 

        mimic agent protocol msg TFTP 5 status
  state:running bytes:1628672 in:3.3 seconds

    • mimic agent protocol msg TFTP session-id stop

      The TFTP data transfer (after start) can be terminated by stop command with a valid session-id. This command will also start the action script by setting the global variable gStatus = interrupted. If the stop command is called before start, then it will just close the TFTP session. A sample exchange for this command would be: 

        mimic agent protocol msg TFTP 5 stop
    Back to Top

  6. Compatibility

    7. This section details interoperability with some widely available TFTP servers.

    Tftpd32    Fedora Linux    WinAgents   

    Back to Top

    Tftpd32

    Download UrlVersionSize
    http://tftpd32.jounin.net/ 2.80173 Kb

    Installation and usage

    1. Extract the tftpd32.280.zip file.
    2. Run tftpd32.exe from the Extracted Location.
    3. Click settings, Change the base directory to a location of your choice.
    4. Click Ok, to confirm changes.
    5. Click "TFTP server" tab to watch transaction logs.

    Uninstallation

    1. Execute the uninst.exe file.
    Back to Top

    Fedora Linux

    TFTP daemon comes with Fedora Linux distribution.

    Download UrlVersionSize
    http://fedora.redhat.com/ 3(depending on installation)

    Installation and usage

    1. To start TFTP daemon with a system boot, set the "disable" field in configuration file /etc/xinetd.d/tftp to "no".
    2. The default directory for saved files is /tftpboot .
    3. To allow saving a file to the server, by default, the file name must already exist. And its permission must allow all users to write.
    4. To allow downloading a file from the server, by default, the file must allow all users to read.

    Uninstallation

    1. Your choice of uninstallation procedure in linux.
    Back to Top

    WinAgents

    Download UrlVersionSize
    http://www.winagents.com/ 3.01.66MB

    Installation and usage

    1. Run the tftsetup.exe file.
    2. Use the "TFTP Service Configuration" Start menu item to choose a location for saving files.
    3. Click Ok, to confirm changes.
    4. Use the "Service Manager" Start menu item to start or stop TFTP service.

    Uninstallation

    1. Use the "Uninstall TFTP Service" Start menu item.
    Back to Top
    << Previous Section    Next Section >>