Wireshark · Wireshark-dev: [Wireshark-dev] Future of extcap "API"

[Jirka Novak <j.novak@xxxxxxxxxxxx>]

Hi,

  I'm resending this email to wireshark-dev to ask bigger audience...

  Text below is about extcap - capability of wireshark to create custom 
programs which can feed wireshark with packets.
  I'm using it and I'm trying to improve it, but I'm stuck and I need 
to discuss how to proceed.
  I'm aware the email is long, but I'm kindly asking to read it by 
everyone who is interested in extcap API.

  I'm calling it API even I don't think it is real API. From my point 
of view it is more or less set of conventions how to use pipes and 
STDIN/STDOUT/STDERR to communicate between wireshark and custom program.

  Background:
  I'm working on ciscodump extcap for several months. During this work 
I fixed UI issues, improved how UI remembers extcap settings and 
improved ciscodump. Ciscodump works now fine from my point of view.
  There is just one last important issue which is caused by extcap API...

  ciscodump is simple application:
a) user sets how many packets wants to capture (!)
b) based on parameters it connects to cisco box
c) configures it to capture packets and prints them in hexdump
d) gets hexdumps and passes them to wireshark, it counts packets and 
when limit is reached, it ends reading loop
e) cleanups configuration

  I didn't created ciscodump, I'm just extending it. And from first 
time I seen the tool, it was weird to me why there is a). How and why I 
should know in advance, how many packets I should capture.
  For code is easier to know count of packets in advance, but it can be 
changed and for many cisco platforms the number is not needed anymore 
even it is still used in the code.
  The reason for a) and the issue is c) and e). Mainly e) must be done 
in every case. And I found that there is use case which extcap API do 
not support and causes that e) is not done.

  Use case:
  When a user stops capture before reaching count in a), wireshark 
terminates the tool and it has no chance to cleanup. For that reason the 
user can't stop the tool anytime and the only solution is/was to know 
count of packets in advance and ends and cleanups after reaching it.
  BTW there is corner case when there is no data in network and count 
of packets is never reached. In this case you must stop capture and e) 
is not done.
  The missing feature I call graceful shutdown of extcap.

  Note:
  The issue looks like ciscodump issue, but I believe that same need of 
cleanup have many advanced extcaps. They are just not part of public 
source tree. Improvement was already requested #17131 and noted in #16447.

  Extcap API:
i)  When extcap is started, dumpcap pass name of pipe to it and where it 
expects captured data.
ii)  STDOUT/STDERR is used to report messages/errors of extcap to 
wireshark, but it is shown/evaluated at the end of capture which 
triggers e.g. #17827. STDIN is closed/not used.
iii)  There is option that extcap can support control pipes - 
bidirectional channel between wireshark and extcap where extcap can 
show/control options shown in wireshark, can provide capture progress etc.
iv) When wireshark wants to stop capture, extcap is terminated (kill or 
equal operation on other OSes).

  Now I want to implement graceful shutdown. I mean that wireshark 
notify extcap it should end, cleanup and terminates. If extcap do not 
finish graceful shutdown in time (timer), it is killed as before.

  My original idea was to use control pipes (iii) above). But current 
implementation is deeply bound to UI and to support UI controls.
  Another drawback of control pipes is that it is quite complex to use 
it and BTW there is no C/C++ library which implements it for extcaps.
  I spend a lot of time checking control pipe code and it is possible 
to separate it from UI, extend it and etc. But my point of view is that 
it will break every existing extcap which uses it and again it will 
increase complexity of every extcap which whould like to use it.

  So I tried to search something more simple and I found how dumpcap is 
terminated. Wireshark creates pipe when starting dumpcap and dumpcap 
reads it, but it is empty so it hangs there.
  When wireshark would like to stop it, it just prints anything to the 
pipe and dumpcap ends.
  So I copied idea and put it to extcap as !5489. It works fine and 
looks simple (much simpler than control pipes).

  The drawback of !5489 is that it adds additional single purpose pipe 
to extcap API and e.g. Stig Bjørlykke pointed it out (thank you for your 
time and support). I agree with this note, but as I wrote above, I'm 
afraid that control pipes are not solution.
  So I'm stuck there...

  I think extcap API should support:
1) Simple extcaps which ends and can be terminated anytime without any 
issue (e.g. randpkt)
2) Extcaps which requires graceful shutdown (e.g. ciscodump)
3) Extcaps which requires UI interaction - control pipes (e.g. 
extcap_example.py)

  I think that 2) and 3) are independent. They can use common API, but 
my point of view is that it will add complexity to tools which requires 
just 2) or just 3).

  I'm kindly asking for comments and for other ideas how to improve 
extcap API to introduce graceful shutdown of extcap.

					Best regards,

						Jirka Novak