.\"	$NetBSD: mtrace6.8,v 1.3 2001/04/26 23:19:50 wiz Exp $
.\"	$KAME: mtrace6.8,v 1.5 2000/12/04 07:02:27 itojun Exp $
.\"
.\" Copyright (C) 1999 WIDE Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 12, 1999
.Dt MTRACE6 8
.Os
.Sh NAME
.Nm mtrace6
.Nd print IPv6 multicast path from a source to
a receiver
.Sh SYNOPSIS
.Nm
.Op Fl d Ar destination
.Op Fl g Ar gateway
.Op Fl h Ar hops
.Op Fl i Ar interface
.Op Fl m Ar maxhops
.Op Fl n
.Op Fl r Ar response_addr
.Op Fl w Ar waittime
.Ar source
.Ar group
.Sh DESCRIPTION
.Nm
utilizes a tracing feature implemented in multicast routers that is
accessed via an extension to the MLD protocol. A trace query is
passed hop-by-hop along the reverse path from the
.Ar destination
to the
.Ar source ,
collecting hop addresses, packet counts, and routing error conditions
along the path, and then the response is returned to the requestor.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d Ar destination
Specifies the multicast receiver that the query wants to trace.
It is the host running
.Nm mtrace6
by default.
.It Fl g Ar gateway
Send the trace query via unicast directly to the multicast router
.Ar gateway .
The unicast router must be the last-hop router on the path from the
intended source to the receiver.
.Ar gateway
can also be a multicast address that the last hop router joins.
.It Fl h Ar hops
Set
.Ar hops
to the IPv6 hop limit field of query packets. The default is 64.
.It Fl i Ar interface
Specifies the local interface (on a multi-homed host) for sending
the trace query and as the default for the receiver and the response
destination.
.It Fl m Ar maxhops
Set to
.Ar maxhops
to the maximum number of hops that will be traced from the receiver
back toward the source. The default is 127 hops.
.It Fl n
Print hop addresses numerically rather than symbolically and numerically
(saves a nameserver address-to-name lookup for each router found on
the path).
.It Fl r Ar response_addr
Specify the host that the trace response sends to.
By default, the response will send to the host running
.Nm mtrace6 .
.It Fl w Ar waittime
Set the time to wait for a trace response to
.Ar waittime
seconds. The default is 3 seconds.
.El
.Sh SEE ALSO
.Xr pim6dd 8 ,
.Xr pim6sd 8 ,
.Xr mtrace 8
.Sh BUGS
Multicast trace for IPv6 is experimental. MLD types for query and
response, and packet format are not officially defined.
.Pp
.Ar waittime
specified by the
.Fl w
option is currently meaningless.
.Sh HISTORY
The
.Nm mtrace6
command first appeared in WIDE/KAME IPv6 protocol stack kit.