Telnet Server

Telnet Server routines allow command line access to an embedded module of an IP network. More...

Functions
uint32_t	telnet_server_message (telnetServerMessage msg, char *buf, uint32_t len)
	Request message for Telnet server session.
uint32_t	telnet_server_process (const char *cmd, char *buf, uint32_t buflen, uint32_t *pvar)
	Process and execute a command requested by the Telnet client.
bool	telnet_check_command (const char *cmd, const char *user_cmd)
	Check command string for a command.
bool	telnet_check_password (uint8_t user_id, const char *password)
	Check user account password in the user database.
uint8_t	telnet_check_username (const char *username)
	Check if an user account exist in the user database.
netStatus	telnet_server_set_delay (uint32_t delay)
	Set a delay between two consecutive calls to telnet_server_process function.
netStatus	telnet_server_get_client (uint8_t *ip_addr, uint8_t *mac_addr)
	Get IP and MAC address of connected remote machine.
int32_t	telnet_server_get_session (void)
	Get current session number of Telnet server.
uint8_t	telnet_get_user_id (void)
	Retrieve the user identification.
bool	telnet_server_message_poll (int32_t session)
	Poll the upper-layer user application for unsolicited messages.
bool	telnet_accept_client (const uint8_t *ip_addr, uint16_t port)
	Accept or deny connection from remote Telnet client.
enum	telnetServerMessage {   telnetServerWelcome,   telnetServerPrompt,   telnetServerLogin,   telnetServerUsername,   telnetServerPassword,   telnetServerLoginFailed,   telnetServerLoginTimeout,   telnetServerUnsolicitedMessage }
	Telnet Server Messages. More...

Description

Telnet Server routines allow command line access to an embedded module of an IP network.

Telnet is most often used for remote login. A user typically opens a Telnet connection to a remote server. The server then treats the Telnet client like a local terminal and allows the user to log in and access the server's resources as if the user was using a directly-attached terminal. Telnet is used this way quite extensively by Linux users, who often need to log in to remote hosts from their local machines.

Note

The page Telnet Server gives you more information on the actual usage of the functions and how to work with them in a project.

Code Examples

Telnet Server User Interface Template

The following source code is part of the Telnet_Server_UIF.c template file. This code template enables the developer to define application specific commands, command responses and to create a list of hosts that are allowed to connect to the Telnet server:

#include <stdio.h>
#include "rl_net.h"
 
// Request message for Telnet server session.
uint32_t telnet_server_message (telnetServerMessage msg, char *buf, uint32_t len) {
  uint32_t rlen = 0;
 
  switch (msg) {
    case telnetServerWelcome:
      // Initial welcome message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "\r\n"
                           "Telnet Server ready\r\n");
      */
      break;
    case telnetServerPrompt:
      // Prompt message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Cmd> ");
      */
      break;
    case telnetServerLogin:
      // Login welcome message, if authentication is enabled
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Embedded Telnet Server\r\n"
                           "\r\n"
                           "Please login...");
      */
      break;
    case telnetServerUsername:
      // Username request login message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Username: ");
      */
      break;
    case telnetServerPassword:
      // Password request login message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Password: ");
      */
      break;
    case telnetServerLoginFailed:
      // Incorrect login error message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Login incorrect");
      */
      break;
    case telnetServerLoginTimeout:
      // Login timeout error message
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Login timeout\r\n");
      */
      break;
    case telnetServerUnsolicitedMessage:
      // Unsolicited message (ie. from basic interpreter)
      /* Example
      rlen = sprintf (buf, "\r\n"
                           "Unsolicited message\r\n");
      */
      break;
  }
  return (rlen);
}
 
// Poll the upper-layer user application for unsolicited messages.
bool telnet_server_message_poll (int32_t session) {
  /* Example
  extern bool msg_available;
 
  if (session == 1 && msg_available == true) {
    // Allow unsolicited messages on 1st session
    msg_available = false;
    return (true);
  }
  */
  return (false);
}
 
// Process a command and generate response.
uint32_t telnet_server_process (const char *cmd, char *buf, uint32_t buflen, uint32_t *pvar) {
  uint32_t len = 0;
 
  /* Example
  extern int32_t AD_in (int32_t channel);
 
  if (telnet_check_command (cmd, "ADIN0") == true) {
    // Read analog input 0
    len = sprintf (buf, "\r\n"
                        " ADIN0 = %d", AD_in(0));
    return (len);
  }
  // ...
  if (telnet_check_command (cmd, "BYE") == true) {
    // Generate reply and disconnect
    len = sprintf (buf, "\r\n"
                        "Disconnecting\r\n");
    return (len | (1u<<30));
  }
  */
  return (len);
}

Telnet Server Multiuser Template

The following source code is part of the Telnet_Server_Multiuser.c template file, which handles Multi-user Authentication for the Telnet server:

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t telnet_check_username (const char *username) {
  /* Example
  if (strcmp (username, "guest") == 0) {
    // Username is correct
    return (1);
  }
  */
  return (0);
}
 
// Check user account password in the user database.
bool telnet_check_password (uint8_t user_id, const char *password) {
  /* Example
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  */
  return (false);
}

Parameter for:

• telnet_server_message

Enumeration Type Documentation

enum telnetServerMessage

Telnet Server Messages.

Enumerator:

telnetServerWelcome	Initial welcome message.
telnetServerPrompt	Prompt message.
telnetServerLogin	Login welcome message, if authentication is enabled.
telnetServerUsername	Username request login message.
telnetServerPassword	Password request login message.
telnetServerLoginFailed	Incorrect login error message.
telnetServerLoginTimeout	Login timeout error message.
telnetServerUnsolicitedMessage	Unsolicited message (ie. from basic interpreter)

Function Documentation

bool telnet_accept_client	(	const uint8_t *	ip_addr,
		uint16_t	port
	)

Accept or deny connection from remote Telnet client.

Parameters

[in]	ip_addr	IP address of the remote Telnet client.
[in]	port	port number of the remote Telnet client.

Returns

• true = Connection from the remote client is allowed.
• false = Connection is denied.

The function telnet_accept_client checks if a connection from the remote client is allowed. This allows remote client filtering. You can selectively decide which clients are allowed to connect to the Telnet server.

The argument ip_addr points to a buffer containing the four octets that make up the IP address of the remote machine.

The argument port specifies the port on the remote machine.

The function is in the Telnet_Server_Access.c module.

Note

This function is optional. If it does not exist in the project, the library default function is used. The library default function accepts all remote clients.

Code Example

#include "rl_net.h"
 
// Accept or deny connection from remote Telnet client.
// If this function is missing, all remote clients are accepted.
bool telnet_accept_client (const uint8_t *ip_addr, uint16_t port) {
  /* Example
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Accept connection.
    return (true);
  }
  // Deny connection.
  return (false);
  */
  return (true);
}

bool bool telnet_check_command	(	const char *	cmd,
		const char *	user_cmd
	)

Check command string for a command.

Parameters

[in]	cmd	pointer to command string from Telnet client.
[in]	user_cmd	user command to check for (in upper case).

Returns

• true = Command found in command string.
• false = Command not found.

The function telnet_check_command compares the command in the buffer cmd with the string user_cmd.

Code Example

// Process a command and generate response.
uint32_t telnet_server_process (const char *cmd, char *buf, uint32_t buflen, uint32_t *pvar) {
  TCP_INFO *tsoc;
  uint8_t ip_addr[IP_ADDR_LEN];
  uint8_t mac_addr[ETH_ADDR_LEN];
  uint32_t val,ch,temp;
  uint32_t len = 0;
 
  ...
  // Simple command line parser
  len = strlen (cmd);
  if (telnet_check_command (cmd, "LED") == true) {
    // LED command given, control on-board LEDs
    if (len >= 5) {
      sscanf (cmd+4,"%x", &val);
      LED_Out (val);
      len = 0;
      if (LEDrun == true) {
        len = sprintf (buf," --> Running Lights OFF");
        LEDrun = false;
      }
      return (len);
    }
    len = 0;
    if (LEDrun == false) {
      len = sprintf (buf," --> Running Lights ON");
      LEDrun = true;
    }
    return (len);
  }
}

bool telnet_check_password	(	uint8_t	user_id,
		const char *	password
	)

Check user account password in the user database.

Parameters

[in]	user_id	user identification number.
[in]	password	pointer to password.

Returns

• true = password accepted.
• false = invalid password.

The function telnet_check_password authenticates the password for a specified user ID on the server.

The argument user_id is the identification number of a user.

The argument password points to a 0-terminated string representing the password that gets checked.

The function is in the Telnet_Server_Multiuser.c module.

Note

This function is optional. It is only needed for multi-user authentication.

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t telnet_check_username (const char *username) {
  /* Example
  if (strcmp (username, "guest") == 0) {
    // Username is correct
    return (1);
  }
  */
  return (0);
}
 
// Check user account password in the user database.
bool telnet_check_password (uint8_t user_id, const char *password) {
  /* Example
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  */
  return (false);
}

uint8_t telnet_check_username

(

const char *

username

)

Check if an user account exist in the user database.

Parameters

[in]

username

pointer to username.

Returns

status information:

• User identification number or
• 0 if the user is not existing.

The function telnet_check_username authenticates the user name and returns the user identification number.

The argument username points to a 0-terminated string representing the user name that must be checked.

The function is in the Telnet_Server_Multiuser.c module.

Note

This function is optional. It is only needed for multi-user authentication.

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t telnet_check_username (const char *username) {
  /* Example
  if (strcmp (username, "guest") == 0) {
    // Username is correct
    return (1);
  }
  */
  return (0);
}
 
// Check user account password in the user database.
bool telnet_check_password (uint8_t user_id, const char *password) {
  /* Example
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  */
  return (false);
}

uint8_t telnet_get_user_id

(

void

)

Retrieve the user identification.

Returns

user identification number (0 = system administrator).

The function telnet_get_user_id retrieves the user identification number when the Telnet console is protected with user authentication. It can be used to disable restricted commands for unprivileged users.

Note

This function returns a value of 0 for system administrator account.

Code Example

//coming soon

netStatus telnet_server_get_client	(	uint8_t *	ip_addr,
		uint8_t *	mac_addr
	)

Get IP and MAC address of connected remote machine.

Parameters

[out]	ip_addr	pointer to IP address.
[out]	mac_addr	pointer to MAC address.

Returns

status code that indicates the execution status of the function as defined with netStatus.

The function telnet_server_get_client provides information about the remote machine that has connected to the Telnet server.

The argument ip_addr points to the IP address of the remote machine.

The argument mac_addr points to the MAC address of the remote machine.

Note

• You can use the function to restrict machines which are allowed to perform system changes.
• For PPP or SLIP links, the MAC address is set to 00-00-00-00-00-00.

Code Example

//coming soon

int32_t telnet_server_get_session

(

void

)

Get current session number of Telnet server.

Returns

current session number.

The function telnet_server_get_session retrieves the current session number of the Telnet server for further usage.

Code Example

//coming soon

uint32_t telnet_server_message	(	telnetServerMessage	msg,
		char *	buf,
		uint32_t	len
	)

Request message for Telnet server session.

Parameters

[in]	msg	code of requested message.
[out]	buf	output buffer to write the message to.
[in]	len	length of the output buffer in bytes.

Returns

number of bytes written to output buffer.

The function telnet_server_message provides the connection and login messages to the Telnet server, when requested. The Telnet server sends these messages to the Telnet client.

The argument msg specifies the type of message that the Telnet server requires:

Message	Description
telnetServerWelcome	To inform the user that the user's Telnet client has connected to the Telnet server.
telnetServerPrompt	To inform the user that the Telnet server is ready and waiting for a command.
telnetServerLogin	Displayed only when user authentication is enabled.
telnetServerUsername	To inform the user to enter the username.
telnetServerPassword	To inform the user to enter the password.
telnetServerLoginFailed	To inform the user that the login is incorrect.
telnetServerLoginTimeout	To inform the user that the login has timed out.
telnetServerUnsolicitedMessage	To write unsolicited messages from the high-layer user application (for example a basic interpreter).

The argument buf points to the output buffer where the telnet_server_message must write the message.

The argument buflen specifies the length of the output buffer in bytes.

You must customize the function in Telnet_Server_UIF.c.

Note

• The length of the output buffer (buflen), might vary because buffer length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. It is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or even less.
• If the telnet_server_message function writes more bytes than buflen into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.
• The Telnet server does not automatically expand the carriage return (CR) character. The telnet_server_message function must write the carriage return and line feed (LF) characters into the buffer to indicate the end of each message.

Code Example

#include <stdio.h>
#include "rl_net.h"
 
// Request message for Telnet server session.
uint32_t telnet_server_message (telnetServerMessage msg, char *buf, uint32_t len) {
  uint32_t rlen = 0;
 
  switch (msg) {
    case telnetServerWelcome:
      // Initial welcome message
      rlen = sprintf (buf, "\r\n"
                           "\r\n"
                           "Telnet Server ready\r\n");
      break;
    case telnetServerPrompt:
      // Prompt message
      rlen = sprintf (buf, "\r\n"
                           "Cmd> ");
      break;
    case telnetServerLogin:
      // Login welcome message, if authentication is enabled
      rlen = sprintf (buf, "\r\n"
                           "Embedded Telnet Server\r\n"
                           "\r\n"
                           "Please login...");
      break;
    case telnetServerUsername:
      // Username request login message
      rlen = sprintf (buf, "\r\n"
                           "Username: ");
      break;
    case telnetServerPassword:
      // Password request login message
      rlen = sprintf (buf, "\r\n"
                           "Password: ");
      break;
    case telnetServerLoginFailed:
      // Login incorrect 
      rlen = sprintf (buf, "\r\n"
                           "Login incorrect");
      break;
    case telnetServerLoginTimeout:
      // Login timeout error message
      rlen = sprintf (buf, "\r\n"
                           "Login timeout\r\n");
      break;
    case telnetServerUnsolicitedMessage:
      // Unsolicited message (ie. from basic interpreter)
      rlen = sprintf (buf, "\r\n"
                           "Unsolicited message\r\n");
      break;
  }
  return (rlen);
}

bool telnet_server_message_poll

(

int32_t

session

)

Poll the upper-layer user application for unsolicited messages.

Parameters

[in]

session

session identification, when multiple connections are active.

Returns

• true = User application has a pending message to send.
• false = No messages pending to send exist.

The function telnet_server_message_poll polls the upper-layer user application for unsolicited messages.

The Telnet session handle parameter session identifies the remote host when many Telnet connections are active at the same time.

You may customize the function in Telnet_Server_UIF.c.

Code Example

// Poll the upper-layer user application for unsolicited messages.
bool telnet_server_message_poll (int32_t session) {
  extern bool msg_available;
 
  if (session == 1 && msg_available == true) {
    // Allow unsolicited messages on 1st session
    msg_available = false;
    return (true);
  }
  return (false);
}

uint32_t telnet_server_process	(	const char *	cmd,
		char *	buf,
		uint32_t	buflen,
		uint32_t *	pvar
	)

Process and execute a command requested by the Telnet client.

Parameters

[in]	cmd	pointer to command string from Telnet client.
[out]	buf	output buffer to write the return message to.
[in]	buflen	length of the output buffer in bytes.
[in,out]	pvar	pointer to a session's local buffer of 4 bytes. 1st call = set to 0, 2nd call = not altered by the system, 3rd call = not altered by the system, etc.

Returns

number of bytes written to output buffer.

• result len | (1u<<31) = repeat flag, the system calls this function again for the same command string.
• result len | (1u<<30) = disconnect flag, the system disconnects the Telnet client.

The function telnet_server_process processes and executes the command requested by the Telnet client. The Network Component's Telnet server calls the unction when it receives the consecutive Carriage Return (CR) and Line Feed (LF) character sequence from the Telnet client (this is usually produced by the user pressing Enter on the Telnet client terminal).

The argument cmd points to the message containing the command that is received from the Telnet client.

The argument buf points to the output buffer where the tnet_process_cmd must write the message to be returned to the Telnet client.

The argument buflen specifies the length of the output buffer in bytes.

The argument pvar is a pointer to a variable that never gets altered by the Telnet Server. You can use *pvar as a repeat counter or simply to distinguish between different function calls.

You must customize the function in Telnet_Server_UIF.c.

Note

• The length of the output buffer (buflen), might vary because buffer length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. It is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or even less.
• If the function writes more bytes than buflen into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.
• The Telnet server does not automatically expand the CR character. The function must write the CR and LF characters into the buffer to indicate the end of each message.
• The argument pvar is private to each Telnet Session. The Telnet Server clears the data in the pvar pointer to 0 before the function is called for the first time in each session.

Code Example

// Process a command and generate response.
uint32_t telnet_server_process (const char *cmd, char *buf, uint32_t buflen, uint32_t *pvar) {
  uint32_t len = 0;
 
  extern int32_t AD_in (int32_t channel);
 
  if (telnet_check_command (cmd, "ADIN0") == true) {
    // Read analog input 0
    len = sprintf (buf, "\r\n"
                        " ADIN0 = %d", AD_in(0));
    return (len);
  }
  // ...
  if (telnet_check_command (cmd, "BYE") == true) {
    // Generate reply and disconnect
    len = sprintf (buf, "\r\n"
                        "Disconnecting\r\n");
    return (len | (1u<<30));
  }
  return (len);
}

netStatus telnet_server_set_delay

(

uint32_t

delay

)

Set a delay between two consecutive calls to telnet_server_process function.

Parameters

[in]

delay

time period to wait in number of 100ms ticks.

Returns

status code that indicates the execution status of the function as defined with netStatus.

The function telnet_server_set_delay ensures that the Telnet server does not call the telnet_server_process function until a certain time period expires.

The argument delay specifies the time period to wait, in number of timer ticks.

Code Example

//coming soon