Get-NNTP Cmdlet

Parameters   Output Objects   Config Settings  

The Get-NNTP component is used to read articles on Usenet news servers.

Syntax

Get-NNTP [parameters]

Remarks

The Get-NNTP cmdlet implements a standard Usenet news reader as specified in RFC 977. It can be used to browse Usenet news groups and read and articles.

To get a listing of all available news groups on a server, set the Server parameter. The Credential parameter can be used optionally for authentication. This will return a separate Newsgroup object for each newsgroup found on the server.

Setting the Newsgroup parameter will instruct the cmdlet to obtain a listing of the most recent articles in the server, resulting in a separate NNTPArticleHeaders object for each message found. The list can be filtered by setting the Range parameter to the range of articles to retrieve or by setting the List parameter to the number of most recent articles to be listed. If neither is set, all messages in the newsgroup will be listed.

To view the contents of an article, set the View parameter to the article number of the message to retrieve. This will return an NNTPArticle object containing the contents of the message.

The cmdlets support pipeline input for some of their parameters. Prebuilding an object and piping it to the cmdlet is very useful, but should be used with caution to prevent security conflicts. Steps have been taken to decrease the risk of a possibly accidental pipe to the cmdlet, for instance, the Credential parameter cannot be piped to the cmdlet and must be specified manually.

# list newsgroups get-nntp -server msnews.microsoft.com | out-host -paging # list the last 10 articles on a newsgroup get-nntp -server msnews.microsoft.com -newsgroup microsoft.public.test -list 10 # retrieve a specific article get-nntp -server msnews.microsoft.com -newsgroup microsoft.public.test -view 8176721

Connection Handling

This cmdlet supports persistent connections through the Connection parameter. To establish a new NNTP connection, use the Connect-NNTP cmdlet. To close the connection, use the Disconnect-NNTP cmdlet.

Parameter List

---

The following is the full list of the parameters of the cmdlet with short descriptions. Click on the links for further details.

Connection	An already established connection.
LogFile	The location of a file to which debug information is written.
CertPassword	The password to the certificate store.
CertStore	The name of the certificate store for the client certificate.
CertStoreType	The type of certificate store for the client certificate.
CertSubject	The subject of the certificate used for client authentication.
Config	Specifies one or more configuration settings.
Credential	The PSCredential object to use for user/password authentication.
FirewallHost	Name or IP address of firewall.
FirewallPassword	A password if authentication is to be used when connecting through the firewall.
FirewallPort	The port of the firewall to which to connect.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
Force	Forces the component to accept the default behavior instead of querying the user.
List	The most recent articles to include in the NNTP operation.
LocalIP	The IP address of the local interface to use.
LogFile	The location of a file to which debug information is written.
Newsgroup	The newsgroup for the component to operate on.
Password	The password to use for authentication.
Port	The TCP port in the remote host to which to connect.
Range	The range of articles.
Server	The address of the Server.
SSL	Determines how the component starts SSL negotiation.
SSLAccept	The encoded public key of the certificate which is to be trusted explicitly.
Timeout	The maximum time allowed for the operation.
User	The username to use for authentication.
View	The article number to view.

Output Objects

---

The following is the full list of the output objects returned by the cmdlet with short descriptions. Click on the links for further details.

Newsgroup	Represents a newsgroup in the listing.
NNTPArticle	An object representing an article on the news server.
NNTPArticleHeaders	The message headers for the newsgroup message.

Config Settings

---

The following is a list of config settings for the cmdlet with short descriptions. Click on the links for further details.

ArticleInfoLimit	Instructs component to save the amount of articles specified that are returned by the server when a GroupOverview event is fired.
GroupInfoLimit	Instructs component to save the amount of group info objects specified that are returned by the server after a ListGroups call has been made.
MaxHeaderLength	Maximum length for headers to avoid line folding (default 80).
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the component whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the component binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
ProxyExceptionsList	A semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
TcpNoDelay	Whether or not to delay when sending packets.
UseIPv6	Whether to use IPv6.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
UseInternalSecurityAPI	Whether or not to use the system security libraries or an internal implementation.

LogFile Parameter (Get-NNTP Cmdlet)

The location of a file to which debug information is written.

Syntax

Get-NNTP -LogFile string

Remarks

When specified, the cmdlet will log debug information to the file. If the file exists, the information will be appended.

Default Value

null

Connection Parameter (Get-NNTP Cmdlet)

An existing NNTP connection.

Syntax

Get-NNTP -Connection NNTPConnection

Remarks

Represents an existing, persistent NNTP connection to be used. After this cmdlet executes, the connection will remain opened to be used in an another call. New connections can be established using the Connect-NNTP cmdlet and closed using the Disconnect-NNTP cmdlet.

Default Value

null

Parameter Position

0

CertPassword Property (Get-NNTP Cmdlet)

The password to the certificate store.

Syntax

Get-NNTP -CertPassword string

Remarks

Specifies a password (if required) to access the specified certificate store.

Default Value

""

Parameter Alias

CertificatePassword

CertStore Property (Get-NNTP Cmdlet)

The name of the certificate store for the client certificate.

Syntax

Get-NNTP -CertStore string

Remarks

The CertStoreType parameter specifies the type of the certificate store specified by CertStore. If the store is password protected, specify the password in CertPassword.

CertStore is used in conjunction with the CertSubject parameter in order to specify client certificates. If CertStore has a value, and CertSubject has been set, a search for a certificate is initiated during logon. Please refer to the CertSubject parameter for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this parameter must be set to the name of the file.

Default Value

"MY"

Parameter Alias

CertificateStore

CertStoreType Property (Get-NNTP Cmdlet)

The type of certificate store for the client certificate.

Syntax

Get-NNTP -CertStoreType string

Remarks

This parameter can take one of the following values:

Default Value

0

CertSubject Property (Get-NNTP Cmdlet)

The subject of the certificate used for client authentication.

Syntax

Get-NNTP -CertSubject string

Remarks

During the user authentication phase of the logon process, the cmdlet will search the store specified in CertStore for a certificate that matches this parameter. If the store contains a private key for that certificate, it is used to verify the user's identity with the secure server.

When this parameter is set, a search is performed in the current certificate store certificate with matching subject.

If an exact match is not found, the store is searched for subjects containing the value of the parameter.

When setting the parameter to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

-certsubject "Test"

If a match is not found, the parameter is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

Default Value

"*"

Config Property (Get-NNTP Cmdlet)

Specifies one or more configuration settings.

Syntax

Get-NNTP -Config string[]

Remarks

The Config parameter takes one or more name-value pairs that represent the name of the configuration setting and value, i.e.: -config "Name=Value"

Default Value

null

Credential Property (Get-NNTP Cmdlet)

The PSCredential object to use for user/password authentication.

Syntax

Get-NNTP -Credential PSCredential

Remarks

Every cmdlet that supports user authentication will expose a Credential parameter. A PSCredential object should be specified for this parameter. Alternatively, the User and Password parameters can be set to represent the credential information.

If the cmdlet supports client key authentication it uses the password field of this object for the certificate's password. This setting is enabled by using public key authentication. Note: Due to security reasons, it is recommended that you use the Credential parameter rather than User and Password to specify the authentication information.

Default Value

null

Parameter Position

1

Parameter Alias

auth

FirewallHost Property (Get-NNTP Cmdlet)

Name or IP address of firewall.

Syntax

Get-NNTP -FirewallHost string

Remarks

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost parameter is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost parameter is set to the corresponding address. If the search is not successful, an error is returned.

Default Value

""

FirewallPassword Property (Get-NNTP Cmdlet)

A password if authentication is to be used when connecting through the firewall.

Syntax

Get-NNTP -FirewallPassword string

Remarks

If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to authenticate against the firewall.

Default Value

""

FirewallPort Property (Get-NNTP Cmdlet)

The port of the firewall to which to connect.

Syntax

Get-NNTP -FirewallPort int

Remarks

The TCP port for the FirewallHost. See the description of the FirewallHost parameter for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType parameter for details. Setting this parameter will overwrite the default settings for the firewall port as specified by FirewallType.

Default Value

0

FirewallType Property (Get-NNTP Cmdlet)

Determines the type of firewall to connect through.

Syntax

Get-NNTP -FirewallType string

Remarks

The applicable values are the following:

Default Value

0

FirewallUser Property (Get-NNTP Cmdlet)

A user name if authentication is to be used connecting through a firewall.

Syntax

Get-NNTP -FirewallUser string

Remarks

If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to authenticate against the firewall.

Default Value

""

Force Property (Get-NNTP Cmdlet)

Forces the component to accept the default behavior instead of querying the user.

Syntax

Get-NNTP -Force SwitchParameter

Remarks

The Force parameter is especially useful in a script environment where user interaction is not an option. Certain cmdlets that are SSH and SSL based will query the user if the security credentials of the certificate presented by the server are not met. Setting this parameter will force the cmdlet to accept the certificate of the server unconditionally.

Default Value

false

List Property (Get-NNTP Cmdlet)

The most recent articles to include in the NNTP operation.

Syntax

Get-NNTP -List int

Remarks

The number of the most recent articles to retrieve. If set to 0, the cmdlet will retrieve all articles in the current newsgroup.

Default Value

0

Parameter Alias

Last

LocalIP Property (Get-NNTP Cmdlet)

The IP address of the local interface to use.

Syntax

Get-NNTP -LocalIP string

Remarks

This parameter is useful when the cmdlet is running on a machine that has more than one network interface (each with its own IP address and network access privileges).

Default Value

""

Parameter Alias

LocalAddress

LogFile Property (Get-NNTP Cmdlet)

The location of a file to which debug information is written.

Syntax

Get-NNTP -LogFile string

Remarks

When specified, the cmdlet will log debug information to the file. If the file exists, the information will be appended.

Default Value

""

Newsgroup Property (Get-NNTP Cmdlet)

The newsgroup for the component to operate on.

Syntax

Get-NNTP -Newsgroup string

Remarks

If no newsgroup is specified, the cmdlet will perform a newsgroup listing on the newsserver.

Default Value

""

Parameter Position

1

Parameter Alias

group

Password Property (Get-NNTP Cmdlet)

The password to use for authentication.

Syntax

Get-NNTP -Password string

Remarks

Every time User, or Password are set, the cmdlet will authenticate with the server. It is recommended that the Credential parameter is set instead of User/Password because of security reasons. If both Credential and this parameter is set, the Credential value is used.

Default Value

""

Port Property (Get-NNTP Cmdlet)

The TCP port in the remote host to which to connect.

Syntax

Get-NNTP -Port int

Remarks

Port specifies a service port on the remote host to which to connect.

A valid port number (a value between 1 and 65535) is required for the connection to take place.

Default Value

119

Range Property (Get-NNTP Cmdlet)

The range of articles.

Syntax

Get-NNTP -Range string

Remarks

If default "-" value is used, all articles will be retrieved.

Default Value

"-"

Server Property (Get-NNTP Cmdlet)

The address of the Server.

Syntax

Get-NNTP -Server string

Remarks

The cmdlet requires a server address to be provided. Either an IP address or the server host name can be provided.

Default Value

""

Parameter Position

0

This is a required parameter.

SSL Property (Get-NNTP Cmdlet)

Determines how the component starts SSL negotiation.

Syntax

Get-NNTP -SSL string

Remarks

SSL may have one of the following values:

Default Value

3

SSLAccept Property (Get-NNTP Cmdlet)

The encoded public key of the certificate which is to be trusted explicitly.

Syntax

Get-NNTP -SSLAccept string

Remarks

Ordinarily, the certificate presented by the server will be checked against the system certificate stores to see if the Certificate Authority is trusted, and if not, the cmdlet will prompt the user to accept the certificate. Setting this parameter will override the system settings and trust the certificate provided.

After each connection, regardless of whether or not the certificate was trusted, the cmdlet will store the certificate presented by the server in the $SSLServerCertificate session variable. This variable can be inspected to view details of the server's certificate.

If the Force parameter is set, the cmdlet will accept the server's certificate unconditionally.

In cases where the certificate presented by the server is not trusted, a prompt will be shown to the user. This prompt will allow the user to decide whether or not they would like to accept the certificate presented by the server.

There may be cases where you do not want a prompt to be displayed or would like to handle the response supplied directly within your script. This can be done by setting the $SSLAcceptPreference variable prior to running the cmdlet. The available values for this variable are:

Default Value

""

Parameter Alias

Accept

Timeout Property (Get-NNTP Cmdlet)

The maximum time allowed for the operation.

Syntax

Get-NNTP -Timeout int

Remarks

After the specified interval in seconds, the cmdlet will throw a Timeout error if the operation is not completed.

Default Value

10

User Property (Get-NNTP Cmdlet)

The username to use for authentication.

Syntax

Get-NNTP -User string

Remarks

Every time User and Password are set, the cmdlet will authenticate with the server. It is recommended that the Credential parameter is set instead of User/Password because of security reasons. If both Credential and this parameter is set, the Credential value is used.

Default Value

""

View Property (Get-NNTP Cmdlet)

The article number to view.

Syntax

Get-NNTP -View int

Remarks

The article number to view. If the article number is not known, try doing a list for recent articles first.

Default Value

0

Parameter Position

2

Newsgroup Output Object (Get-NNTP Cmdlet)

Represents a newsgroup in the listing.

Syntax

Object Newsgroup {
   string Group;
   bool CanPost;
   long FirstArticle;
   long LastArticle;
}

Remarks

The FirstArticle and LastArticle properties can be used to construct a log with the range of articles for all newsgroups on the server.

NNTPArticle Output Object (Get-NNTP Cmdlet)

An object representing an article on the news server.

Syntax

Object NNTPArticle {
   string MessageId;
   string Headers;
   string References;
   string Message;
}

Remarks

When the View parameter is used, the cmdlet will return a single NNTPArticle object.

MessageId contains the unique message ID of the article as reported by the server.

Headers contains the complete headers of the article.

References contains the References article header is created for the article, showing the message ID's to which the posted article refers.

Article contains the contents of the article body.

NNTPArticleHeaders Output Object (Get-NNTP Cmdlet)

The message headers for the newsgroup message.

Syntax

Object NNTPArticleHeaders {
   long Number;
   string Subject;
   string FromName;
   string FromEmail;
   string Date;
   long Size;
   string References;
   string MessageId;
   string Otherheaders;
}

Remarks

When the Newsgroup parameter is specified the cmdlet will return an NNTPArticleHeaders object for every article returned.

Number contains the number of the article in the group.

Subject contains the subject of the article.

FromName contains the friendly name of the article author.

FromEmail contains the email address of the article author.

Date contains the date the article was posted.

Size contains the size of the article in bytes.

References contains the message ids for the articles this article refers to (separated by spaces).

MessageId contains the unique message ID for the article.

OtherHeaders contains any other article headers that the news server returns for the article.

Config Settings (Get-NNTP Cmdlet)

The cmdlet accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the cmdlet, access to these internal properties is provided through the Config method.

NNTP Config Settings

TCPClient Config Settings

Socket Config Settings

Base Config Settings