Skip to content
23 changes: 15 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# Contributing

Contributions are welcome: issues, fixes and features alike. Before
sending a change, run `make test` (see [docs/testing.md](docs/testing.md)).
We accept contributions: issues, fixes and new features. Before you send
a change, run `make test` (refer to [docs/testing.md](docs/testing.md)).

Write all technical documentation in ASD-STE100 Simplified Technical
English. Follow [docs/STYLE.md](docs/STYLE.md).

## The contributor agreement

Expand Down Expand Up @@ -50,9 +53,13 @@ does it):
It says that you agree to the above for that commit. A contribution
without it cannot be merged.

A check on each pull request looks for that line, with the commit
author's email, on every commit. If it's missing, `git rebase --signoff
main` (or `git commit --amend -s` for the last commit) adds it; then
force-push. Pull requests from the D-Modem Authors themselves (the
repository's owner and the D-Modem organization's members) are not
checked.
A check on each pull request looks for that line on every commit. The
line must have the email address of the commit author. If the line is
missing, do these steps:

1. Add the line with `git rebase --signoff main`. For the last commit
only, you can use `git commit --amend -s`.
2. Force-push the branch.

The check does not examine pull requests from the D-Modem Authors (the
owner of the repository and the members of the D-Modem organization).
52 changes: 27 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,15 @@

# modemmenu

A login and menu for dial-up callers, the first thing a caller sees once
the modems connect.
modemmenu is a login and a menu for dial-up callers. When the modems
connect, the caller sees modemmenu first.

modemmenu asks for a user name and password, shows the message of the
day and offers a menu of what the caller may do: a bulletin board, PPP
dial-up networking, a shell, or any program. It runs behind
[D-Modem](https://github.com/D-Modem/D-Modem)'s Asterisk module,
`app_dmodem`, one process per call or one server for all of them.
modemmenu asks for a user name and a password. Then it shows the message
of the day and a menu of the tasks that the caller can do. These tasks
include a bulletin board, PPP dial-up networking, a shell or any other
program. modemmenu runs behind `app_dmodem`, the Asterisk module of
[D-Modem](https://github.com/D-Modem/D-Modem). It can run as one process
for each call or as one server for all calls.

```
Welcome to D-Modem.
Expand All @@ -33,19 +34,19 @@ Main menu
Selection: ppp
```

- Logins from a users file, LDAP, SQL (MySQL/MariaDB, PostgreSQL, SQLite) or system accounts through PAM
- PPP dialers detected (AutoPPP and PAP), with a pppd plugin
- The classic AOL client dialing in: AOLnet, SprintNet and Tymnet played, then the line to a BBS's AOL host
- Menus with access by user and group, guests and self sign-up
- The menu full screen on ANSI and VT terminals (a 90s blue desk, the bar moved with the cursor keys; only what changed is sent, for slow lines), lines for the others
- `modemmenu -setup`: the configuration on full screens with pull-down menus and the sample's help, for the sysop at the console or calling in
- Each item starts with the caller's credentials and the call's details: dialed number, caller ID, connect rate, time
- Drop files for doors, last callers, and handing a caller to another menu
- A ready-made FreePBX setup ([freepbx/](freepbx/README.md))
- Logins from a users file, LDAP, SQL (MySQL/MariaDB, PostgreSQL, SQLite) or system accounts through PAM.
- Detection of PPP dialers (AutoPPP and PAP), with a pppd plugin.
- Support for the classic AOL client when it dials in. modemmenu emulates AOLnet, SprintNet and Tymnet. Then it connects the line to the AOL host of a BBS.
- Menus with access by user and by group, guest access and self sign-up.
- A full-screen menu on ANSI and VT terminals, and a line menu on other terminals. The full-screen menu looks like a blue desktop from the 1990s. The cursor keys move the bar. For slow lines, modemmenu sends only the changes to the screen.
- `modemmenu -setup`: full screens with pull-down menus and the help text from the sample, to change the configuration. The sysop can use them at the console or on a call.
- Each item starts with the credentials of the caller and the details of the call: dialed number, caller ID, connect rate and time.
- Drop files for doors, a list of the last callers, and the transfer of a caller to a different menu.
- A FreePBX configuration that is ready to use ([freepbx/](freepbx/README.md)).

## Quick start

Go 1.22 or later:
You must have Go 1.22 or later. Do these steps:

```
make # with PAM when libpam's headers are there
Expand All @@ -54,15 +55,15 @@ modemmenu -config /etc/asterisk/modemmenu.conf -check # check the configuratio
modemmenu -config /etc/asterisk/modemmenu.conf -setup # or change it on a full screen
```

then point an `app_dmodem` profile at it ([docs/running.md](docs/running.md)).
Then configure an `app_dmodem` profile to use modemmenu ([docs/running.md](docs/running.md)).

## Documentation

The documentation is also a website, [d-modem.github.io/menu](https://d-modem.github.io/menu/), with reference pages made from the code.
The documentation is also a website, [d-modem.github.io/menu](https://d-modem.github.io/menu/). Some reference pages on the website come from the code.

[docs/](docs/README.md) has building, running, configuration,
authentication, PPP, security and the tests.
[samples/modemmenu.conf.sample](samples/modemmenu.conf.sample) has every option.
[docs/](docs/README.md) has information about these topics: the build,
operation, configuration, authentication, PPP, security and the tests.
[samples/modemmenu.conf.sample](samples/modemmenu.conf.sample) has all the options.

## The D-Modem suite

Expand All @@ -80,6 +81,7 @@ authentication, PPP, security and the tests.

AGPL-3.0-only ([LICENSE](LICENSE)), or a commercial licence from the D-Modem Authors ([COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)). Contributions come with a contributor agreement ([CONTRIBUTING.md](CONTRIBUTING.md)).

If you modify modemmenu and offer it to callers, the AGPL's section 13
has you offer them its source: a menu item, the banner or the message of
the day naming where it is will do.
If you change modemmenu and offer it to callers, section 13 of the AGPL
tells you to offer them its source code. To do this, give the location
of the source code in a menu item, in the banner or in the message of
the day.
20 changes: 10 additions & 10 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# modemmenu documentation

- [Building](building.md): Go, PAM, `make install`
- [Running it from app_dmodem](running.md): a program per call, one server on a unix socket, FreePBX
- [Configuration](configuration.md): `modemmenu.conf`, the connect rate, terminals, the message of the day, the menu (full screen or lines) and its items, guests and sign-up, caller ID, time limits, drop files, last callers, handing callers on
- [Configuration reference](reference.md): every section and key, from the sample
- [The sysop's setup](setup.md): `modemmenu -setup`, the configuration on a full screen, and on the line for sysops
- [Authentication](authentication.md): users file, LDAP, SQL, system accounts (PAM), changing passwords, the auth socket
- [PPP dialers](ppp.md): AutoPPP and PAP, the pppd plugin
- [AOL callers](aol.md): the classic AOL client dialing in, its network played
- [Security notes](security.md)
- [Tests](testing.md)
- [Building](building.md): Go, PAM and `make install`.
- [Running it from app_dmodem](running.md): one program for each call, one server on a unix socket, and FreePBX.
- [Configuration](configuration.md): `modemmenu.conf`, the connect rate, terminals, the message of the day, the menu (full screen or lines) and its items, guests and sign-up, caller ID, time limits, drop files, last callers, and the transfer of callers to a different program.
- [Configuration reference](reference.md): all sections and keys, from the sample.
- [The sysop's setup](setup.md): `modemmenu -setup`, to change the configuration on a full screen, at the console or on the line.
- [Authentication](authentication.md): users file, LDAP, SQL, system accounts (PAM), password changes and the auth socket.
- [PPP dialers](ppp.md): AutoPPP and PAP, and the pppd plugin.
- [AOL callers](aol.md): the classic AOL client when it dials in, and the emulation of its network.
- [Security notes](security.md).
- [Tests](testing.md).

The samples: [modemmenu.conf.sample](../samples/modemmenu.conf.sample), [modemmenu.users.sample](../samples/modemmenu.users.sample), [modemmenu.pam.sample](../samples/modemmenu.pam.sample), [modemmenu.service.sample](../samples/modemmenu.service.sample), [modemmenu-authd.service.sample](../samples/modemmenu-authd.service.sample).
142 changes: 142 additions & 0 deletions docs/STYLE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Documentation style: ASD-STE100 Simplified Technical English

All technical documentation in the D-Modem project uses ASD-STE100
Simplified Technical English (STE). This guide gives the rules that we use.
It applies to READMEs, the `docs/` folders, wikis, specifications, design
documents, protocol write-ups, CONTRIBUTING files (except legal text) and
technical notes in the project files.

The official source is the ASD-STE100 specification (Issue 9) and its
dictionary. If this guide and the specification are different, use the
specification. You can get the specification free of charge from
<https://www.asd-ste100.org>.

## 1. What STE does not change

Do not change these items. Copy them exactly:

- Code, commands, file names, paths, URLs, identifiers and configuration keys.
- AT commands, S-registers, result codes and protocol message names.
- Numbers, units, addresses, offsets and register values.
- Titles of standards (for example, ITU-T V.92) and quotations from them.
- Product names, company names and the names of people.
- Legal text: licenses, the contributor agreement, copyright and trademark
notices. Legal text keeps its legal wording.
- Text that we copied from a third party (for example, `ORIGINAL-readme.txt`
files, firmware release notes, test fixtures).

## 2. Words

1. Use approved words from the STE dictionary, with their approved meaning
only. For example, "close" means "to move to the closed position". It
does not mean "near".
2. Use technical names (Category: technical names). For example: modem,
handshake, carrier, codec, constellation, packet, socket, thread,
buffer, firmware, sample rate, call, line, PBX, trunk, server, client.
3. Use technical verbs (Category: technical verbs) for processes that STE
does not cover. This project uses these technical verbs: build, compile,
link, configure, install, uninstall, boot, flash, download, upload, dial,
log in, log out, debug, decode, encode, modulate, demodulate, train,
retrain, negotiate, sign, encrypt, decrypt, compress, decompress, parse,
render, cache, merge, commit, push, clone, emulate, probe.
4. Use one word for one thing. Do not change between synonyms. For example,
if you write "softmodem", do not write "software modem" in the next
paragraph.
5. Use these verb forms only: infinitive, imperative, simple present, simple
past, simple future, and the past participle as an adjective.
6. Do not use "-ing" forms of verbs, except in technical names (for example,
"ring signal", "echo canceller"). Write "the modem starts to train", not
"the modem is training".
7. Do not use phrasal verbs. Write "start", not "start up". Write "find",
not "find out".
8. Do not make noun clusters of more than three words. Use prepositions to
break up longer clusters. Write "the receive buffer of the V.34 data
pump", not "the V.34 data pump receive buffer".
9. Use articles ("the", "a") and demonstrative adjectives ("this", "these")
before nouns where possible.
10. Do not use slang, idioms, contractions ("can't", "it's") or Latin
abbreviations ("e.g.", "i.e.", "etc."). Write "for example", "that is",
"and other items".

### Common replacements

| Do not write | Write |
|---|---|
| utilize, make use of | use |
| ensure, make certain | make sure |
| require, need to | is necessary, must |
| should | must (a rule) or write what occurs (a fact) |
| allow, enable (a person) | let, make it possible |
| approximately, roughly | about |
| perform, carry out | do |
| obtain, fetch, grab | get |
| prior to | before |
| in order to | to |
| via | through |
| currently | now |
| additional | more |
| e.g., i.e., etc. | for example, that is, and other items |
| turn on / turn off (a setting) | enable / disable (technical verbs for software settings) |
| set up (verb) | configure, install |
| figure out, find out | find, calculate |
| it's, can't, don't | it is, cannot, do not |

## 3. Sentences

1. Write one topic in one sentence.
2. Procedural sentences (instructions): 20 words or fewer.
3. Descriptive sentences: 25 words or fewer.
4. Use the active voice. In descriptive text, you can use the passive voice
only when you do not know who or what does the action.
5. Do not use semicolons to join sentences. Write two sentences.
6. Use a colon before a list. Use a vertical list when there are more than
two items.
7. Use connecting words ("then", "but", "if", "because") to show how two
sentences are related.

## 4. Procedures

1. Write instructions in the imperative ("Install the package").
2. Write one instruction in one sentence. You can write two actions in one
sentence only when the reader does them at the same time.
3. Write each step as a numbered item.
4. If a condition applies, write the condition first: "If the build fails,
delete the `build/` folder."
5. Put a warning or a caution before the step that it applies to. Do not put
it at the end of the procedure.
6. Write the result of a step in a separate sentence after the step, if the
reader must know it.

## 5. Descriptive writing

1. Give the most important information first.
2. Write one topic in one paragraph.
3. Do not write more than six sentences in a paragraph.
4. Use headings to divide long text into short sections.
5. Use tables for data that has rows and columns.

## 6. Warnings and cautions

Use a warning for a risk to persons. Use a caution for a risk to equipment,
data or the telephone line. Start with a short title, then the instruction,
then the risk:

> **CAUTION: DO NOT CONNECT THE BOARD TO A LIVE LINE WITHOUT THE ISOLATION
> TRANSFORMER.** The line voltage can cause damage to the codec.

## 7. Examples

| Before | After (STE) |
|---|---|
| You'll need to make sure the PBX is set up before you dial out. | Configure the PBX before you dial. |
| The handshake is performed by the answering modem, which then starts sending ANSam. | The answering modem starts the handshake. Then it sends ANSam. |
| Turn it off if it's causing trouble. | If this feature causes problems, disable it. |
| `crypto/tls` can't take such a hello, and it can't be rewritten for it. | `crypto/tls` cannot accept this type of hello. Also, you cannot change `crypto/tls` to accept it. |

## 8. Check before you commit

- Are all sentences short (20 words for instructions, 25 for descriptions)?
- Is each instruction in the imperative, with one action?
- Is there a word with "-ing", a phrasal verb or a contraction?
- Are code, commands and identifiers exactly the same as before?
- Did you keep legal text and third-party text unchanged?
60 changes: 33 additions & 27 deletions docs/aol.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

## The classic AOL client, dialing in

AOL's own client (2.5 to 4.0) never types at a login prompt. It dials a
network, AOLnet, SprintNet or Tymnet, and its CCL script answers that
network's prompts. Then it speaks P3, AOL's own protocol, to the AOL host.
With `[aol] enabled = yes`, modemmenu plays the network and then joins the
line to `host`. That is [D-Modem/bbs](https://github.com/D-Modem/bbs)'s
AOL front end (`[aol]` there), where the caller signs on with their BBS
The AOL client (versions 2.5 to 4.0) never types at a login prompt. It
dials a network (AOLnet, SprintNet or Tymnet), and its CCL script answers
the prompts of that network. Then it uses P3, the protocol of AOL, to
communicate with the AOL host. With `[aol] enabled = yes`, modemmenu
emulates the network. Then it connects the line to `host`. That host is
the AOL front end of [D-Modem/bbs](https://github.com/D-Modem/bbs)
(`[aol]` in its configuration). There, the caller signs on with the BBS
name and password.

```
Expand All @@ -16,27 +17,32 @@ enabled = yes
host = localhost:5190
```

modemmenu tells which network the client expects from what its script
does at the login prompt. The strings are the ones AOL 3.0's
`AOLNET.CCL`, `SPRINT.CCL` and `TYMNET.CCL` wait for.
modemmenu finds the network that the client expects from the actions
of its script at the login prompt. The strings are the strings that
`AOLNET.CCL`, `SPRINT.CCL` and `TYMNET.CCL` of AOL 3.0 wait for.

| Network | The script | modemmenu |
|---|---|---|
| AOLnet | waits for `UQKT1`, answers `aol` | says `UQKT1` before the first login prompt, then `CONNECTED` |
| SprintNet | sends `@D` | asks `TERMINAL=`, gives the `@` prompt, answers `par? 11` with the line's speed, and `C <address>` with `<address> CONNECTED` |
| Tymnet | sends `A`, with no line end | asks `PLEASE LOG IN:`, answers the login with `+` and the host's name with `CALL CONNECTED` |
| P3 | a script of one's own that starts P3 at once | joins the line to the host at the first packet |

In the client's Setup, add the D-Modem line's phone number as an access
number of the network to play, and pick it.

`networks` limits which of these modemmenu plays. Leave out `aolnet` to
keep its `UQKT1` line off every caller's screen. With AOLnet or SprintNet
played, the names `aol` and `@D` at the login prompt are the client's,
not a user's. A caller's name beginning with `A` is still a name, because
a person types on while the Tymnet script waits seconds for an answer.

The call is logged (`AOL client (sprintnet) at the login prompt`, then
`aol: to localhost:5190`, then how long it lasted). modemmenu's own
logins, time limits and menus don't apply to it: the BBS signs the caller
on and keeps its own limits.
| AOLnet | waits for `UQKT1`, answers `aol` | sends `UQKT1` before the first login prompt, then `CONNECTED` |
| SprintNet | sends `@D` | asks `TERMINAL=`, gives the `@` prompt, answers `par? 11` with the speed of the line, and answers `C <address>` with `<address> CONNECTED` |
| Tymnet | sends `A`, with no line end | asks `PLEASE LOG IN:`, answers the login with `+`, and answers the name of the host with `CALL CONNECTED` |
| P3 | a custom script that starts P3 immediately | connects the line to the host at the first packet |

In the Setup of the client, do these steps:

1. Add the phone number of the D-Modem line as an access number of the
network that modemmenu must emulate.
2. Select that access number.

`networks` limits the networks that modemmenu emulates. If you remove
`aolnet`, the `UQKT1` line does not show on the screen of each caller. If
modemmenu emulates AOLnet or SprintNet, the names `aol` and `@D` at the
login prompt come from the client, not from a user. A name that starts
with `A` is still a user name. The Tymnet script waits some seconds for
an answer, but a person continues to type.

modemmenu records the call in the log. It records
`AOL client (sprintnet) at the login prompt`, then
`aol: to localhost:5190`, then the duration of the call. The logins, time
limits and menus of modemmenu do not apply to this call. The BBS signs
the caller on and applies its own limits.
Loading
Loading