back2roots/padua

home *** CD-ROM | disk | FTP | other *** search

/ back2roots/padua / padua.7z / padua / uucp / AGetty_exp.lha / man / AGetty.doc next >

Wrap

Text File | 1993-05-15 | 23.4 KB | 500 lines

$VER: AGetty_Manual v0.203 (15-May-93) Copyright ⌐ 1993 by Peter Simons All rights reserved. AGetty is Freeware, meaning you may spread and use it without any limitations or fees. But all rights are reserved to me and I may decide to release future versions as shareware or even as part of a commercial package. WHAT IS IT? ----------- AGetty is similar to the well-known Getty included in Matt Dillon's AmigaUUCP package. It hangs on the specified serial port (serial.device unit 0 by default) waiting for connections via the connected modem. Once a connection is detected, AGetty provides a Login: request to the caller. Getty disconnects any caller who cannot provide a legal Login and Password within 60 seconds. It also allows only 3 login attempts before disconnecting. Any attempt to login with an illegal password will be written to the logfile. Upon receiving a legal Login and Password, verified via the "PASSWD"-file, AGetty will execute a specified program, usually UUCICO or PMail, and stay off the line until the program returns. Then, AGetty will disconnect the caller and reset the modem, returning to its original state. WHY SHOULD I USE THIS GETTY INSTEAD OF THE ORIGINAL? ---------------------------------------------------- AGetty and Getty do absolutely the same thing, so why should you use this new version? The question is easy to answer: Because the original Getty is totally outdated. This Getty: - provides the devicelocking machanism supported by all the major terminal programs such as VLT, Term, X-Comm and Terminus, to name a few. - is completely localized when Workbench v2.1 is installed - is pure and can be made resident. This saves valuable memory on systems serving several lines, because every AGetty-task uses the same code. - supports the new features of OS 2.04, like user-friendly command line-help, quick-io etc... - is about 20kbyte smaller than the old one and needs less than 4kbyte stack and only 20kbyte memory during operation. - draws your attention to logins rejected because an incorrect password was specified. - has the ability to loan the used modem-port to another program that supports the OwnDevUnit.Library. - recognizes incoming calls by the "RING"-message returned by the modem instead of relying on the modem-autoanswer. This reduces the probability of failed calls that used to occur when the old Getty was busy while the modem made the connect. ;-) - allows to store login-informations (like username or realname) into local shell variables, what is required by certain scripts or applications like Taylor UUCP. - is written by me (save the best for last)! THE MODEM --------- AGetty works only with hayes compatible modems, which understand the AT-command set. AGetty uses locked DTR-rate and RTS/CTS-handshaking all the time. I didn't find it necessary to make this configurable, but if I get some responses complaining about this, I'll add a switch to the config-file. The modem is expected to return strings (eg. "OK", "ERROR", "NO CARRIER"), not errorcodes. Modems auto-answer has to be disabled. INSTALLATION ------------ The installation of AGetty is quiet easy: Just copy the files in the "libs"-directory to your "LIBS:". (You should call "Avail flush" or even better reset your amiga to make sure older versions of the libraries are flushed.) Then copy the "c/AGetty"-executable somewhere in your commandpath, usually "UUCP:c". AGetty may be made resident using the shell-command "Resident". Depending on how you extracted the AGetty archive you may have to set AGetty's pure bit before this will work. You can do this with the CLI command protect AGetty +p The advantage of making AGetty resident is that AGetty is loaded once into memory and can then be used by several tasks at the same time. The file "lib/AGetty.config" must be copied into a directory pointed at by a "UULIB:" assign. The other files in the "lib"-directory may be copied anywhere (their paths are specified in the config file). Usually they go to "UULIB:", too. If you have Workbench v2.1 installed, copy the "catalogs"-directory to your "LOCALE:"-assign (consult your DOS-manual for further information.) to localize AGetty. The path to the catalog-files should be: "LOCALE:catalogs/language_name/AGetty.catalog". COMMANDLINE USAGE ----------------- AGetty recognizes several command line options, but if you edit the Config-file correctly you won't need any to start it. (These options are meant for machines with more than one port, running several AGetties. Using the commandline parameters, so you can start each AGetty with it's own options, without changing the config file every time.) Start AGetty with "?" to get the following template: [DEVICE] [UNIT/N] [BAUD/N] [MODEMINIT] [ANSWERCOMMAND] [LOGINTEXT] [PRI/N] [-A=ANSWER/S] [-S=SINGLERUN/S] [HARDWIRE/S] [QUIT/S] DEVICE - Here you can specify the device AGetty should use to "talk" to the modem. This is useful for owners of multiport serial boards which need a special version of the serial.device. If you leave this entry out, serial.device will be used by default. UNIT/N - This is the device's unit to use. Default is unit 0. BAUD/N - This is the baudrate that should be used to talk to the modem. You should specify the baudrate here or in the config file (later) for correct functioning. MODEMINIT - This is the string/command that should be used to initialize the modem. The string must be terminated with a "\r"-sequence, what means that AGetty sends the command to the modem and waits for response. If anything different from "OK" arrives, AGetty returns with an error. You may even supply whole command sequences to the modem, inserting "\r" after every single command. Example: ATZ\rATS0=0\rATX7\r IMPORTANT: AGetty uses its own method to determine a caller, so you have to disable the modem's auto answer (ATS0=0). Otherwise AGetty won't work correctly. ANSWERCOMMAND - Here you can supply a commandstring that should be used to answer the incomming call. In spite of MODEMINIT, this entry doesn't support and though doesn't need to be closed with a "\r", AGetty appends the return himself. The default command is "ATA". LOGINTEXT - Here you can specify a textfile that should be displayed to every caller. This is somewhat useless for UUCP sites, because programs like UUCico or PMail don't care much about this "welcome text". However, a human caller may get your number accidently and you want to inform him that here isn't anything interesting available. PRI/N - Using this parameter you may change the priority AGetty will run at. Usually you should choose a priority above 0, but not higher than 5. Let's say about 4, okay? :-) The default value is 0. -A=ANSWER/S - If you add this keyword to the commandline, AGetty answers to an existent or non-existent caller immediatly without checking for a "RING" message from the modem. This switch is useful for sites that do not run 24h a day, but rather only for exchanging some programs at special times (like mine). One example: You talk to a friend of yours who tells you something about a program he found on a bbs a few minutes ago. You both have your modem and phone connected to the same line. Just execute "AGetty -A" and he starts his UUCICO/PMail using "ATD" as his dialstring and now you can exchange the archive without calling each other again. After the mailers have transferred the archive you may even go voice again. -S=SINGLERUN/S - This switch must be used together with ANSWER or it will have no effect. If you specify SINGLERUN, AGetty returns immediatly after processing one connection. HARDWIRE/S - Using this switch you can tell AGetty that this port is connected to another machine using a nullmodem. This means that AGetty won't send any modem commands and does not expect a carrier on that line. ATTENTION: This feature is untested! If you need it, supply me with a second Amiga! :-> QUIT/S - If you add this keyword to the commandline, AGetty will look for an AGetty beeing on job for this line and will signal him to quit. This AGetty will terminate as soon as possible, but will complete any running login before. If no AGetty for this device and unit is working, nothing will happen. Another way to terminate AGetty is to send him a CTRL/D break. CONFIGURATION ------------- Let's begin with the easiest part of the configuration: Load the file "lib/Getty-Header" into your favourite editor and write a nice message that will be displayed to any (human) caller. (Of course, you may keep my message but then the shareware fee rises. :->) That was easy, wasn't it? :-)) Now take a look at "lib/AGetty.config". In most cases you can keep the actual value/string for correct functions. Keywords are recognized only when they're placed in the first column. Comment lines must begin with a '#' or ';'. Comments after a keyword are not allowed. The parameter may contain spaces, but it may not end with a space. Leading and trailing blanks are not parsed by AGetty. (Example: "SYSTEMNAME peti is the best" is okay, but "SYSTEMNAME AGetty is the coolest tool under the sun " won't be parsed correctly.) Here's a description of all keywords known to AGetty: STANDARDDEVICE - This is the device that AGetty should use as default. This selection is overridden by the command line. Default is serial.device. STANDARDBAUD - Baud rate to talk to the modem at. Overridden by the command line. This entry must be specified!! No default value is provided. MODEMINIT - The string to initialize the modem. For a brief descrption of how to provide modem commands, please look at the corresponding entry in the commandline sction of the manual. IMPORTANT: AGetty uses its own method to detect calls! You MUST have auto answer disabled (ATS0=0). BRUTEFORCE - "yes" or "no" may follow. This entry decides whether AGetty should wait for the device to become free or should return with an error after 5 seconds. Be careful with "yes": AGetty won't return before the device is freed and can not be interrupted with CTRL/C. IMMEDIATEANSWER - AGetty doesn't use the auto-answer mode of the modem but his own system of recognizing incomming calls. Do you want to AGetty to answer the phone immediatly or would you prefer him waiting for the second ring? The latter reduces the chance of AGetty answering the phone unnecessarily. ANSWERCOMMAND - Here you can provide the default modem command, that should be used to answer incomming calls. This selection is overridden by the command line. Default is "ATA". MYPRI - Here you can specify the prioritity you want AGetty to run at. This is overridden by the command line. Default is 0. LOGFILE - Here you can specify path and name of your logfile. If you comment this entry out, AGetty won't log its activities to a file. LOGINTEXT - Here you can specify the path and name of the (text) file that should be displayed to callers. This is overridden by the command line. PASSWD - Here you can specify the name and path of your password file (described later.). This entry must be specified. No default is provided. USER - For some programs is may be useful if some information PASSWORD (like the login-name or realname) would be available in USERID scripts via DOS-variables. Each of these keywords GROUPID represents a corresponding entry in the passwdfile of FINGER-INFO the actual caller. Behind these keywords you may specify HOME-DIR the name of the variable to hold the information of the COMMAND-TO-RUN passwdfile. The datas are stored in local DOS-variables, please consult your DOS-manual for further information. These variables are set before the command is executed by AGetty and are deleted afterwards. The former contents are not rescued! SETTING UP A SITE ----------------- Okay, your AGetty is configured now, but how does it know what to do when somebody wants to login?? This information is found in the "Passwd"- file usually found in "GETTY:" or "UULIB:". For each system you have to add a line to this file using the following syntax: User,Password,UserID,GroupID,(Finger-Info),Home-Dir,Command-To-Run The fields are seperated with commas ',' and may contain blanks. User - this is the login-name of this guy. As described later in this section, the login-name of somebody needn't necessarily be the same as his systemname. The username is limitied up to 32 characters. Password - this is the password used for that login (not case sensitive) The password is limited up to 32 chars, too. If you specify a single star ("*") as password, AGetty won't ask the user for the password but execute the CommandToRun immediatly. This feature is useful for sites that run UUCP and a BBS at one port. Then the caller could log in with "BBS" or something similar and doesn't have to provide a password. UserID - this field isn't used in this version of AGetty, but has to exist. GroupID - this field isn't used in this version of AGetty, but has to exist. Finger-Info - this field isn't used in this version of AGetty, but has to exist. Home-Dir - Here you can provide an AmigaDOS directory-name. AGetty will make this directory the current one, before he executes the specified command. This may be important for some tools like AXShell. If no home directory is provided, "UUCP:" is used as default. Command-To-Run - this is the command that should be started when the user/machine has logged in successfully. NOTE: The old Getty had an option allowing to preface the command-to-run with a star ("*"). If Getty found this, he redirected the standard i/o of the program to the serial device. This is not supported by AGetty in the current revision, but might be added in the near future. Some examples: quax,peti for president,,,,,UUCPC:PMail quax quax_uucico,peti for president,,,,UUSpool:,UUCPC:UUCico <NULL: >NULL: -USER quax quax_8k,yeah_yeah,,,(Thomas Mildenberger),,UUCPC:PMail quax -XPRLIB xprzmodem8k.library All entries are for the same person or machine, but depending on the login name different commands are called. Programs like PMail or later versions of UUCico allow one to specify the machine name of the caller in the commandline, so you may have different logins but only one machine name. You can interrupt the actual login-attempt by sending a CTRL-C break to AGetty. LOG- AND ERROR-MESSAGES ----------------------- Let's say, you installed AGetty propperly, edited the config- and passwd-file, but it still doesn't do what you whant. What could you do to locate the error? AGetty supplies you with a lot of log- and error messages, if you have Workbench v2.1 installed even in your native language. These messages should tell you anything you need to get rid of the bug. Here's a list of all messages AGetty could possibly display with a short description: "Failed allocating a SignalBit!" - AGetty failed allocating an user signalbit. Perhaps a program in your system doesn't free its allocated signalbits correctly? You'll have to reset your machine... "There's already an AGetty running for that port!" - exactly what it says. :-) "Carrier lost!" - A carrier detected has been expected but no carrier was found. If this happens in a 7wire-connection you'll have to start AGetty with the -7WIRE switch. "Received CTRL/C-Break!" - You can interrupt the current login, modem command or whatever AGetty is doing at the moment with CTRL/C. "Borrowed %s, unit %lu to >%s<" - When an other program tries to allocate the serial.device using the OwnDevUnit.Library, AGetty will be notified. If he doesn't need the device himself at the moment (for an incomming call), he'll free the device for the other task and wait for it to return. "Got %s, unit %lu back" - The other program has freed the device again. "Connect on unit %lu failed!" - connect failure "Couldn't hang up!" - I invested *VERY* much time in AGetty's hang-up mechanism. When AGetty tries to hang up, it sends a carrige return to the modem to interrupt still working modem commands like "ATA". After a short delay the status of the carrier is checked. Is a carrier detected, AGetty sends a "+++" to go into command mode. Then "ATH" is transmitted. After a delay of 2 seconds AGetty checks the carrier again. If the carrier is still detected, AGetty drops the DTR to force the modem to hang up. And if this doesn't have any effect, the above message is displayed. "%s logged into command %s" - A system logged in successfully and the listed command has been executed. "Login failed! login: %s, password: %s" - Someone tried to log in, but couldn't supply a correct login name or password. AGetty asks the caller for login and password, even if the login has already been incorrect. This makes it impossible to hackers to find out wether the users exists or not. The incorrect data are listed here, for your information. "Modem-initialisation failed!" - The Modem returned something different than "OK" during the modem-initialisation, maybe an "ERROR"? Don't worry too much about this error. Most programs I know do not even try to check wether the command was executed corretly, because it is nearly impossible to interpret the strings returned by the modem. Every modem handles certain situations differntly, just one example: I send the modem an "ATZ". During the execution, the modem detects an incomming call. Some modems will interrupt the command and return nothing except the "RING". Other modems will report the "RING" and then finish the command with "OK", etc... FUTURE RELEASES --------------- There's still some work to do for the comming releases of AGetty. The next feature that will be added is fax support and to rewrite AGetty's manual for AmigaGuide, providing cross-references and similar stuff. Then I'll try to add support for AxShell and similar programs, meaning that I add the fido capabilities of Matt's Getty: If the command-to-run is prefaced with a star ("*"), the Getty provides the serial in-/output via STDIN/STDOUT. Additionally, I'd like to add more security to AGetty, regarding local networks and multi-user systems. I'm currently working on a nice encryption feature, what will provide ultimate security for the passwd-file. This is commonly used under UNIX, but quiete unknown on the amiga. One of the easier additions should be a routine that handles human logins better, meaning that AGetty echos the typed characters at the login and filters illegal control-characters. How fast these updates will be released, depends on the amount of feedback I receive. SYSTEM REQUIREMENTS ------------------- AGetty requires Kickstart v37 (Workbench Release 2.0) or higher. Additionally, PTool.Library and OwnDevUnit.Library are required. HOW TO CONTACT ME ----------------- If you want to contact me (e-mail preferred), you may use the following addresses: Snail-Mail: Peter Simons E-Mail: simons@peti.GUN.de (Usenet) Europaring 20 D-5300 Bonn 1 Voice: +49 228 746061 Germany ACKNOWLEDGEMENTS ---------------- First of all, I'd like to appreciate the work of Stefan Thielscher, Frank Bergknecht and Thomas Mildenberger who helped me betatesting the program. Also very important were Christopher A. Wichura and Mike Meyer, who contributed many fine ideas for AGetties improvement and compatibility to the whole UUCP-package. Then I'd like to thank all the guys who installed and used AGetty for a period of time, reporting me any error that occured and helped me to terminate these bugs. And my (famous) last words belong to Marcus Kuba and Matthias Zepf, my all-time favorite fans and supporters.