1Trouble Shooting
2================
3
4Common Pitfalls
5---------------
6
7Generally, the following kinds of errors that may happen at runtime:
8
9#. **A script deadlocks.** In other words, Exscript sends no further
10   commands even though the remote host is already waiting for a
11   command. This generally happens when a prompt is not recognized.
12
13#. **A script executes a command before the remote host is ready.** This
14   happens when a prompt was detected where none was really included in
15   the response.
16
17#. **A script terminates before executing all commands.** This happens
18   when two (or more) prompts were detected where only one was expected.
19
20The following sections explain when these problems may happen and how to
21fix them.
22
23Deadlocks
24---------
25
26Exscript tries to automatically detect a prompt, so generally you
27should not have to worry about prompt recognition. The following prompt
28types are supported:
29
30::
31
32    [sam123@home ~]$
33    sam@knip:~/Code/exscript$
34    sam@MyHost-X123$
35    MyHost-ABC-CDE123$
36    MyHost-A1$
37    MyHost-A1(config)$
38    FA/0/1/2/3$
39    FA/0/1/2/3(config)$
40    admin@s-x-a6.a.bc.de.fg:/$
41
42Note: The trailing "$" may also be any of the following characters:
43"$#>%"
44
45However, in some rare cases, a remote host may have a prompt that
46Exscript can not recognize. Similarly, in some scripts you might want
47to execute a special command that triggers a response that does not
48include a prompt Exscript can recognize.
49
50In both cases, the solution includes defining the prompt manually, such
51that Exscript knows when the remote host is ready. For example,
52consider the following script:
53
54::
55
56    1. show ip int brief
57    2. write memory
58    3. {enter}
59    4. show configuration
60
61Say that after executing line 2 of this script, the remote host asks for
62a confirmation, saying something like this:
63
64::
65
66    Are you sure you want to overwrite the configuration? [confirm]
67
68Because this answer does not contain a standard prompt, Exscript can
69not recognize it. We have a deadlock. To fix this, we must tell
70Exscript that a non-standard prompt should be expected. The
71following change fixes the script:
72
73::
74
75    1. show ip int brief
76    2. {connection.set_prompt(/\[confirm\]/)}
77    3. write memory
78    4. {connection.set_prompt()}
79    5. {enter}
80    6. show configuration
81
82The second line tells Exscript to wait for "[confirm]" after
83executing the following commands. Because of that, when the write memory
84command was executed in line 3, the script does not deadlock (because
85the remote host’s response includes "[confirm]"). In line 4, the prompt
86is reset to it’s original value. This must be done, because otherwise
87the script would wait for another "[confirm]" after executing line 5 and
88line 6.
89
90A Command Is Sent Too Soon
91--------------------------
92
93This happens when a prompt was incorrectly detected in the response of a
94remote host. For example, consider using the following script:
95
96::
97
98    show interface descriptions{extract /^(\S+\d)/ as interfaces}
99    show diag summary
100
101Using this script, the following conversation may take place:
102
103::
104
105    1. router> show interface descriptions
106    2. Interface              Status         Protocol Description
107    3. Lo0                    up             up       Description of my router>
108    4. PO0/0                  admin down     down
109    5. Serial1/0              up             up       My WAN link
110    6. router>
111
112Note that line 3 happens to contain the string "Router>", which looks
113like a prompt when it really is just a description. So after receiving
114the ">" character in line 3, Exscript believes that the router is asking
115for the next command to be sent. So it immediately sends the next
116command ("show diag summary") to the router, even that the next prompt
117was not yet received.
118
119Note that this type of error may not immediately show, because the
120router may actually accept the command even though it was sent before a
121prompt was sent. It will lead to an offset however, and may lead to
122errors when trying to capture the response. It may also lead to the
123script terminating too early.
124
125To fix this, make sure that the conversation with the remote host does
126not include any strings that are incorrectly recognized as prompts. You
127can do this by using the "connection.set_prompt(...)" function as
128explained in the sections above.
129
130The Connection Is Closed Too Soon
131---------------------------------
132
133This is essentially the same problem as explained under "A Command Is
134Sent Too Soon". Whenever a prompt is (correctly or incorrectly)
135detected, the next command is send to the remote host. If all commands
136were already executed and the next prompt is received (i.e. the end of
137the script was reached), the connection is closed.
138
139To fix this, make sure that the conversation with the remote host does
140not include any strings that are incorrectly recognized as prompts. You
141can do this by using the "connection.set_prompt(...)" function as
142explained in the sections above.
143